Tickets de caisse électroniques (E-Receipts)

L'API Tickets de caisse électroniques permet d'émettre, de transmettre et de gérer les tickets de caisse électroniques auprès de l'Agence des revenus italienne à travers une seule intégration. La solution est conçue pour automatiser l'ensemble du processus d'émission des documents commerciaux, en simplifiant la gestion fiscale des points de vente physiques et des logiciels de gestion.

Avec Openapi, vous pouvez configurer les entreprises, les établissements, les Stores, les caisses enregistreuses télématiques et les caissiers, afin de créer une infrastructure complète pour la gestion des tickets de caisse électroniques. Une fois la configuration terminée, chaque Store est prêt à émettre des documents commerciaux, gérer les retours, les annulations et suivre toutes les opérations via l'API.

L'API couvre l'ensemble du cycle de vie des tickets de caisse électroniques : de la configuration initiale à l'émission, la consultation et la gestion des opérations ultérieures, en offrant une intégration évolutive adaptée aux entreprises disposant de plusieurs points de vente.

La solution est conçue pour les logiciels de gestion, les systèmes POS, les plateformes ERP, les applications retail et toutes les solutions qui souhaitent intégrer la gestion des tickets de caisse électroniques directement dans leurs processus opérationnels.

Toutes les opérations sont gérées via une infrastructure dédiée aux Tickets de caisse électroniques, permettant d'administrer l'ensemble de l'environnement à partir d'une seule intégration API.

Configuration de l'entreprise, des Stores et des caisses enregistreuses

POST /IT-configurations

La configuration est la première étape indispensable pour utiliser l'API Tickets de caisse électroniques. Cet endpoint permet d'enregistrer l'entreprise et de configurer toute l'infrastructure nécessaire à la gestion des documents commerciaux.

Au cours de cette phase, vous pouvez configurer le siège de l'entreprise, créer un ou plusieurs Stores (points de vente), associer une ou plusieurs caisses enregistreuses télématiques à chaque Store et configurer les callbacks afin de recevoir automatiquement les notifications relatives aux opérations effectuées par l'API.

Chaque Store peut gérer une ou plusieurs caisses enregistreuses télématiques, tandis que chaque ticket de caisse électronique peut être associé à la caisse enregistreuse utilisée pour émettre le document commercial.

EXEMPLE DE REQUÊTE

Pour configurer votre entreprise, envoyez une requête à POST /IT-configurations. Dans l'exemple suivant, l'entreprise, son siège social, un Store avec deux caisses enregistreuses télématiques ainsi que les callbacks utilisés pour recevoir automatiquement les mises à jour des opérations sont configurés.

{
  "fiscal_id": "YourCompanyFiscal_id",
  "name": "Nom de l'entreprise",
  "email": "[email protected]",
  "receipts": true,
  "customer_invoice": true,
  "supplier_invoice": true,
  "e_receipts": false,
  "legal_storage": false,
  "merchant_address": {
    "street_address": "Rue Principale",
    "street_number": "10",
    "zip_code": "00100",
    "city": "Rome",
    "province": "RM"
  },
  "stores": [
    {
      "label": "Store Centre-ville",
      "address": {
        "street_address": "Rue Principale",
        "street_number": "10",
        "zip_code": "00100",
        "city": "Rome",
        "province": "RM"
      },
      "cash_registers": [
        {
          "label": "Caisse enregistreuse 1"
        },
        {
          "label": "Caisse enregistreuse 2"
        }
      ]
    }
  ],
  "receipts_authentication": {
    "taxCode": "FHHWMF96L52D111B",
    "password": "1234567891****d",
    "pin": "1********4"
  },
  "api_configurations": [
    {
      "event": "receipt",
      "callback": {
        "url": "https://your-server.com/123232"
      }
    },
    {
      "event": "customer_invoice",
      "callback": {
        "url": "https://your-server.com/123232"
      }
    },
    {
      "event": "supplier_invoice",
      "callback": {
        "url": "https://your-server.com/123232"
      }
    },
    {
      "event": "receipt-error",
      "callback": {
        "url": "https://your-server.com/error"
      }
    }
  ]
}

EXEMPLE DE RÉPONSE

Si la configuration est effectuée avec succès, l'API renvoie les informations de l'entreprise enregistrée, les services activés, la configuration des Stores et les caisses enregistreuses télématiques associées. La réponse confirme également que la configuration est active et fournit l'identifiant unique qui sera utilisé pour les opérations de gestion ultérieures.

Émission des tickets de caisse électroniques

POST /IT-e-receipts

L'endpoint POST /IT-e-receipts permet d'émettre un ticket de caisse électronique pour un point de vente physique. Le document est transmis à l'aide du Store (PEM) et de la caisse enregistreuse télématique configurés au préalable via le service IT-configurations.

Pour utiliser ce service, l'option e_receipts doit être activée dans la configuration de l'entreprise, un numéro de TVA italien valide doit être renseigné dans le champ fiscal_id et au moins un Store avec sa caisse enregistreuse télématique associée doit déjà être configuré.

Lors de l'émission du document, vous pouvez spécifier le caissier, le Store et la caisse enregistreuse télématique à utiliser. L'API vérifie automatiquement que les ressources indiquées appartiennent bien à l'entreprise et utilise la configuration associée au Store et à la caisse enregistreuse sélectionnés.

Par défaut, le service émet un ticket de vente (type: sale). Il prend également en charge des scénarios avancés tels que les justificatifs d'achat, les retours et les annulations grâce aux endpoints et aux schémas dédiés décrits dans la documentation.

EXEMPLE DE REQUÊTE

Pour émettre un ticket de caisse électronique, envoyez une requête à POST /IT-e-receipts. Dans l'exemple suivant, un ticket de vente (type: sale) est émis et associé à un Store, une caisse enregistreuse télématique et un caissier préalablement configurés. Le document contient un seul article et un paiement électronique correspondant au montant total du ticket.

{
  "fiscal_id": "11122211133",
  "type": "sale",
  "cashier_id": "69d7c469f6d16f5f4003eca6",
  "store_id": "69ca63ce0f8c187ebf0aa36c",
  "cr_id": "69d8cfbba3ccba0fcc0d0184",
  "items": [
    {
      "type": "goods",
      "id": 1,
      "quantity": "4.00",
      "description": "Souris sans fil premium",
      "unit_price": "2.00",
      "vat_rate_code": "22.00"
    }
  ],
  "electronic_payment_amount": "8.00"
}

EXEMPLE DE RÉPONSE

Si la requête est traitée avec succès, l'API renvoie le nouveau ticket de caisse électronique créé avec son identifiant unique, son numéro de document, sa date d'émission, son état de traitement et toutes les informations fiscales associées au document commercial.

{
  "data": {
    "fiscal_id": "11122211133",
    "type": "sale",
    "cashier_id": "69d7c469f6d16f5f4003eca6",
    "store_id": "69ca63ce0f8c187ebf0aa36c",
    "cr_id": "69d8cfbba3ccba0fcc0d0184",
    "status": "ready",
    "created_at": "2026-04-17T15:30:12.000Z",
    "items": [
      {
        "type": "goods",
        "id": 1,
        "quantity": "4.00",
        "description": "Souris sans fil premium",
        "unit_price": "2.00",
        "vat_rate_code": "22.00",
        "simplified_vat_allocation": false,
        "discount": "0.00",
        "surcharge": "0.00",
        "prepaid_or_voucher": false,
        "complimentary": false
      }
    ],
    "document_number": "0001-0003",
    "document_date": "2026-04-17T17:30:12.000Z",
    "total_amount": 8,
    "is_voidable": true,
    "is_returnable": true
  },
  "success": true,
  "message": "",
  "error": null
}

Consultation des tickets de caisse électroniques

GET /IT-e-receipts

L'endpoint GET /IT-e-receipts permet de récupérer tous les tickets de caisse électroniques émis via l'API. Il offre une vue d'ensemble des documents commerciaux générés sur un ou plusieurs points de vente.

Les résultats peuvent être filtrés à l'aide des paramètres de recherche disponibles, ce qui facilite la consultation, le suivi et la gestion de grands volumes de tickets de caisse électroniques au sein de logiciels de gestion, d'ERP et de plateformes retail.

Chaque document retourné contient les principales informations fiscales ainsi que les identifiants nécessaires pour consulter le détail du ticket ou effectuer des opérations ultérieures, telles que les retours ou les annulations.

EXEMPLE DE REQUÊTE

Pour récupérer les tickets de caisse électroniques, il suffit d'envoyer une requête à GET /IT-e-receipts. Vous pouvez utiliser les paramètres de recherche disponibles afin de filtrer les documents retournés selon les besoins de votre application.

GET /IT-e-receipts

EXEMPLE DE RÉPONSE

Si la requête est traitée avec succès, l'API renvoie la liste des tickets de caisse électroniques correspondant aux critères de recherche. Pour chaque document, elle fournit l'état de traitement, le numéro du document, la date d'émission, les articles vendus, les informations de paiement ainsi que les indicateurs permettant de savoir si le ticket peut encore être annulé ou faire l'objet d'un retour.

{
  "data": [
    {
      "fiscal_id": "11122211133",
      "type": "sale",
      "cashier_id": null,
      "store_id": "69e1f1335c3954b240083fd4",
      "cr_id": "69e1f1335c3954b240083fd5",
      "status": "ready",
      "created_at": "2026-04-17T15:30:12.000Z",
      "items": [
        {
          "type": "goods",
          "id": 1,
          "quantity": "4.00",
          "description": "Souris sans fil premium",
          "unit_price": "2.00",
          "vat_rate_code": "22.00",
          "simplified_vat_allocation": false,
          "discount": "0.00",
          "surcharge": "0.00",
          "prepaid_or_voucher": false,
          "complimentary": false
        }
      ],
      "invoice_issuing": false,
      "uncollected_dcr_to_ssn": false,
      "discount": "0.00",
      "additional_text": null,
      "cash_payment_amount": "0.00",
      "electronic_payment_amount": "8.00",
      "ticket_restaurant_payment_amount": "0.00",
      "ticket_restaurant_quantity": 0,
      "services_uncollected_amount": "0.00",
      "goods_uncollected_amount": "0.00",
      "id": "69e2520543070c786b0c77c4",
      "document_number": "0001-0003",
      "document_date": "2026-04-17T17:30:12.000Z",
      "total_amount": 8,
      "is_voidable": true,
      "is_returnable": true
    }
  ],
  "success": true,
  "message": "",
  "error": null
}

Gestion des retours

PATCH /IT-e-receipts/{id}

L'endpoint PATCH /IT-e-receipts/{id} permet d'effectuer le retour d'un ou de plusieurs articles figurant sur un ticket de caisse électronique déjà émis. L'identifiant du document d'origine est indiqué dans le chemin de la requête, tandis que les articles à retourner et leurs quantités sont définis dans le corps de la requête.

Un retour peut être associé à un caissier, un Store ou une caisse enregistreuse télématique spécifique. Si ces paramètres ne sont pas renseignés, le système utilise automatiquement la caisse enregistreuse télématique ayant émis le ticket d'origine. Avant d'effectuer un retour, vous pouvez utiliser l'endpoint GET /IT-e-receipts/{id}/returnable-items afin de récupérer les articles encore éligibles au retour ainsi que les quantités disponibles.

Les quantités indiquées sont automatiquement validées par rapport au ticket d'origine, empêchant tout retour supérieur aux quantités effectivement disponibles pour chaque article.

EXEMPLE DE REQUÊTE

Pour enregistrer le retour d'un ou de plusieurs articles, envoyez une requête à PATCH /IT-e-receipts/{id} en indiquant les articles à retourner ainsi que leurs quantités. Vous pouvez également spécifier la caisse enregistreuse télématique et le caissier ayant effectué l'opération.

{
  "cr_id": "69e0ad3456b8f49252094fab",
  "cashier_id": "69d7c469f6d16f5f4003eca6",
  "items": [
    {
      "id": 1,
      "quantity": "2.00"
    }
  ]
}

EXEMPLE DE RÉPONSE

Si le retour est traité avec succès, l'API génère un nouveau document commercial de type return, lié au ticket de caisse électronique d'origine via le champ parent_receipt_id. Cela garantit une traçabilité complète de l'opération sans modifier le document initial.

{
  "data": {
    "fiscal_id": "11122211133",
    "type": "return",
    "cashier_id": null,
    "store_id": "69e1f1335c3954b240083fd4",
    "cr_id": "69e1f1335c3954b240083fd5",
    "status": "ready",
    "created_at": "2026-04-17T15:36:57.000Z",
    "items": [
      {
        "type": "goods",
        "id": 1,
        "quantity": "1.00",
        "description": "Souris sans fil premium",
        "unit_price": "2.00",
        "vat_rate_code": "22.00",
        "simplified_vat_allocation": false,
        "discount": "0.00",
        "surcharge": "0.00",
        "prepaid_or_voucher": false,
        "complimentary": false
      }
    ],
    "id": "69e2539a43070c786b0c77c5",
    "parent_receipt_id": "69e2520543070c786b0c77c4",
    "document_number": "0001-0004",
    "document_date": "2026-04-17T17:36:58.000Z",
    "is_voidable": false,
    "is_returnable": false
  },
  "success": true,
  "message": "",
  "error": null
}

Annulation d'un ticket de caisse électronique

DELETE /IT-e-receipts/{id}

L'endpoint DELETE /IT-e-receipts/{id} permet d'annuler un ticket de caisse électronique déjà émis. L'opération ne modifie pas le document d'origine : elle génère un nouveau document d'annulation lié au ticket initial via le champ parent_receipt_id, garantissant ainsi une traçabilité fiscale complète de l'opération.

Vous pouvez également spécifier le caissier, le Store ou la caisse enregistreuse télématique qui effectuera l'annulation. Si ces paramètres ne sont pas renseignés, le système utilise automatiquement la caisse enregistreuse télématique associée au document d'origine.

Un ticket de caisse électronique ne peut être annulé que s'il est encore éligible à l'annulation. Les tickets déjà annulés ou intégralement retournés ne peuvent plus être annulés.

EXEMPLE DE REQUÊTE

Pour annuler un ticket de caisse électronique, envoyez une requête à DELETE /IT-e-receipts/{id} en indiquant l'identifiant du document à annuler. Vous pouvez également inclure le caissier, le Store ou la caisse enregistreuse télématique dans le corps de la requête afin d'identifier la ressource qui effectuera l'opération.

DELETE /IT-e-receipts/69e2584a4a218eb38c03c012

EXEMPLE DE RÉPONSE

Si l'annulation est effectuée avec succès, l'API renvoie un nouveau document de type void, lié au ticket de caisse électronique d'origine via le champ parent_receipt_id. Cela permet de conserver l'historique complet de toutes les opérations effectuées sur le document commercial.

{
  "data": {
    "fiscal_id": "11122211133",
    "type": "void",
    "cashier_id": null,
    "store_id": "69e1f1335c3954b240083fd4",
    "cr_id": "69e1f1335c3954b240083fd5",
    "status": "ready",
    "created_at": "2026-04-17T15:57:10.000Z",
    "id": "69e2585782410398e20c4642",
    "parent_receipt_id": "69e2584a4a218eb38c03c012",
    "is_voidable": false,
    "is_returnable": false
  },
  "message": "Ticket annulé : 69e2584a4a218eb38c03c012",
  "success": true,
  "error": null
}

Gestion des caissiers

Chaque ticket de caisse électronique peut être associé à un caissier spécifique. Grâce aux endpoints dédiés, vous pouvez créer et gérer les caissiers opérant sur vos différents points de vente, attribuer des identifiants individuels et garantir une traçabilité complète de chaque transaction.

La gestion des caissiers est particulièrement utile pour les entreprises disposant de plusieurs opérateurs ou postes d'encaissement, car elle permet d'identifier précisément le caissier ayant émis chaque document commercial.

POST /IT-cashiers

L'endpoint POST /IT-cashiers permet de créer un nouveau caissier pour le service Tickets de caisse électroniques. Chaque caissier dispose de ses propres identifiants et peut être associé aux tickets de caisse électroniques émis via l'API.

EXEMPLE DE REQUÊTE

Pour créer un nouveau caissier, envoyez une requête à POST /IT-cashiers en indiquant son adresse e-mail, son nom complet et le numéro de TVA de l'entreprise à laquelle il sera associé.

{
  "email": "[email protected]",
  "name": "Jean Dupont",
  "fiscal_id": "11122211133"
}

EXEMPLE DE RÉPONSE

Si la requête est traitée avec succès, l'API renvoie le caissier nouvellement créé, avec son identifiant unique, son statut d'activation ainsi que les informations de l'entreprise à laquelle il est associé.

{
  "data": {
    "id": "69d7c469f6d16f5f4003eca6",
    "email": "[email protected]",
    "name": "Jean Dupont",
    "status": "active",
    "fiscal_id": "11122211133"
  },
  "success": true,
  "message": "Caissier créé avec succès",
  "error": null
}

Gestion des Stores et des caissiers

L'API Tickets de caisse électroniques est conçue pour répondre aux besoins des entreprises disposant de plusieurs points de vente et de plusieurs opérateurs. Lors de la configuration initiale, vous pouvez créer un ou plusieurs Stores, associer une ou plusieurs caisses enregistreuses télématiques à chaque Store et gérer les caissiers opérant au sein de votre infrastructure.

Chaque ticket de caisse électronique peut être associé à un Store spécifique, à une caisse enregistreuse télématique et, le cas échéant, au caissier ayant effectué la transaction. Cela garantit une traçabilité complète des documents commerciaux tout en simplifiant la gestion des chaînes de magasins, des entreprises multisites et des organisations disposant de plusieurs postes d'encaissement.

Les endpoints dédiés permettent également de gérer les opérations de maintenance des Stores, notamment leur réactivation, les procédures de clôture journalière ainsi que les communications prévues pour les situations d'urgence, garantissant la conformité avec les processus opérationnels pris en charge par le service.

Automatisez la gestion des tickets de caisse électroniques

L'API Tickets de caisse électroniques permet de gérer l'ensemble du cycle de vie des tickets de caisse électroniques grâce à une seule intégration, depuis la configuration de l'entreprise et des Stores jusqu'à l'émission, la consultation, les retours et les annulations des documents commerciaux.

Grâce à la prise en charge des Stores, des caisses enregistreuses télématiques et des caissiers, la solution s'adapte aussi bien aux points de vente individuels qu'aux entreprises disposant de plusieurs établissements, tout en offrant une intégration évolutive conforme aux processus opérationnels de gestion des tickets de caisse électroniques en Italie.

Grâce à des API REST simples à intégrer et à une documentation complète, vous pouvez automatiser la gestion des tickets de caisse électroniques au sein de logiciels de gestion, de systèmes POS, de plateformes ERP et d'applications retail, tout en réduisant les interventions manuelles et en optimisant les processus opérationnels.