Envoyez des Reçus Électroniques facilement, rapidement et avec des normes de sécurité élevées à l’Agence des Revenus italienne.
Automatisez l’envoi des documents commerciaux via API en temps réel.
Toutes les connaissances dont vous avez besoin
Vous trouverez ici quelques conseils à prendre en compte pour aborder cette API. Si vous préférez, nous fournissons des exemples de code, la documentation OAS3, la possibilité d'essayer l'API en direct via Swagger UI ou d'importer l'intégralité de la collection dans Postman. Nous proposons également un environnement Sandbox où vous pouvez expérimenter toutes sortes de requêtes de manière totalement gratuite.
Obtenir le Token dans la section appropriée avant de commencer.
Gestion de l'entreprise
POST /IT-configurations
Cet endpoint permet de créer une nouvelle configuration pour l'entreprise. Il est possible d'ajouter des identifiants et des URLs de callback pour recevoir des notifications de reçus.
Récupérer les configurations
GET /IT-configurations
Cet endpoint renvoie la liste des configurations enregistrées.
Modifier une configuration existante
PATCH /IT-configurations/{fiscal_id}
Cet endpoint permet de modifier les identifiants ou les URLs de callback associés à une configuration existante.
Supprimer une configuration
DELETE /IT-configurations/{fiscal_id}
Cet endpoint permet de supprimer une configuration. Attention : Si des reçus ont déjà été envoyés, la suppression ne sera pas possible.
Gestion des reçus
Créer un reçu
POST /IT-receipts
Cet endpoint permet d'envoyer un nouveau reçu électronique. Un id unique est généré et une notification est envoyée à l'URL de callback configurée.
Enregistrer un retour
PATCH /IT-receipts/{id}
Cet endpoint permet de mettre à jour un reçu pour enregistrer un retour produit.
Annuler un reçu
DELETE /IT-receipts/{id}
Cet endpoint permet d'annuler un reçu précédemment envoyé. Une notification d'annulation est envoyée à l'URL configurée.
Consulter les reçus
GET /IT-receipts
Cet endpoint renvoie la liste des reçus enregistrés, avec des filtres par date, montant, etc.
- Oas file url https://console.openapi.com/oas/fr/invoice.openapi.json
- Fork or import with Postman
- Production domain invoice.openapi.com
- Sandbox domain test.invoice.openapi.com
-
Production Scopes 8
- POST invoice.openapi.com/IT-configurations
- PATCH invoice.openapi.com/IT-configurations
- GET invoice.openapi.com/IT-configurations
- DELETE invoice.openapi.com/IT-configurations
- POST invoice.openapi.com/IT-receipts
- GET invoice.openapi.com/IT-receipts
- DELETE invoice.openapi.com/IT-receipts
- PATCH invoice.openapi.com/IT-receipts
-
Sandbox Scopes 8
- POST test.invoice.openapi.com/IT-configurations
- PATCH test.invoice.openapi.com/IT-configurations
- GET test.invoice.openapi.com/IT-configurations
- DELETE test.invoice.openapi.com/IT-configurations
- POST test.invoice.openapi.com/IT-receipts
- GET test.invoice.openapi.com/IT-receipts
- DELETE test.invoice.openapi.com/IT-receipts
- PATCH test.invoice.openapi.com/IT-receipts
Invoice (1.0.0)
API pour la gestion de la configuration des factures et des reçus numériques conformément à la réglementation fiscale. Ce service permet aux entreprises de configurer leurs paramètres de facturation et de gérer les reçus, en conformité avec les normes de l'Agence des impôts italienne (Agenzia delle Entrate) en matière de facturation électronique (Fatturazione Elettronica) et de transmission des reçus numériques (Scontrino Elettronico). Il prend en charge l'échange sécurisé de données, la soumission des reçus en temps réel et les mises à jour de configuration pour les exigences en matière de déclaration fiscale.
IMPORTANT : Veuillez noter que vous ne pouvez pas envoyer de reçus entre 23h55 et 00h00 (fuseau horaire italien) à l'Agence des impôts italienne (Agenzia delle Entrate). Pour cette raison, tous les reçus envoyés pendant cette période seront envoyés à la première heure disponible, c'est-à-dire dans les premières minutes du jour suivant.
NB : Il est nécessaire d'activer le code fiscal saisi dans la configuration sous receipts_authentication-taxCode pour l'envoi des reçus. Suivez la procédure décrite sur ce [lien] (https://docs.openapi.it/Procedura-manuale-per-incarico.pdf).
Récupérer toutes les configurations informatiques.
Récupérer toutes les configurations informatiques associées à l'utilisateur. Ce point d'accès renvoie une liste de configurations, y compris les détails fiscaux, les paramètres de notification de l'API. Il permet aux entreprises de gérer leur intégration avec l'administration fiscale et de surveiller les événements liés aux reçus.
Authorizations:
Responses
Response Schema: application/json
Array of objects (ITConfigurationResponse) |
Request samples
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
CURL *hnd = curl_easy_init(); curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET"); curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN"); curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers); CURLcode ret = curl_easy_perform(hnd);
Response samples
- 200
- "data": [
- {
- "fiscal_id": "YourCompanyFiscal_id",
- "name": "nameCompany",
- "receipts_authentication": null,
- "taxCode": "FHHWMF96L52D111B",
- "api_configurations": [
- {
- "event": "receipt",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-error",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- "receipts": true,
- "active": true,
- "create_timestamp": 1738323790,
- "id": "679ca42e**********016f18"
- {
- "fiscal_id": "YourCompanyFiscal_id2",
- "name": "nameCompany2",
- "receipts_authentication": {
- "taxCode": "FHHWMF96L52D111B"
- "api_configurations": [
- {
- "event": "receipt",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-credentials",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-retry",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-error",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- "receipts": true,
- "active": true,
- "create_timestamp": 1738318895,
- "id": "679ca42e**********016df7"
- "success": true,
- "message": "",
- "error": null
Créer une nouvelle configuration informatique.
La configuration informatique est un outil utilisé pour définir et gérer les données de l'entreprise pour votre propre entreprise. Elle fonctionne comme une entité représentant une entreprise gérée par votre compte. Cette configuration permet de personnaliser différents paramètres
IMPORTANT : Pour recevoir une notification, il est nécessaire d'insérer les api_configurations et de définir l'événement comme indiqué dans les schémas. Il sera toujours possible de mettre à jour les données avec la configuration PATCH IT
Pour envoyer des reçus, il est nécessaire d'activer l'option receipts à true.
Par défaut, toutes les options sont réglées sur false.
Il sera possible de configurer gratuitement jusqu'à 10 entreprises par jour, après quoi le prix indiqué sera appliqué
Authorizations:
Request Body schema: application/json
fiscal_id required | string L'identifiant fiscal unique (numéro de TVA ou code fiscal) de l'entreprise enregistrée auprès de l'Agenzia delle Entrate. |
name required | string Nom de la société ou de l'entité associée à l'identifiant fiscal. |
email required | string <email> L'adresse électronique utilisée pour la communication et les notifications. Elle ne peut pas être modifiée après la création de la configuration. |
receipts | boolean Indique si le système doit traiter les reçus numériques. |
object Informations d'authentification requises pour la soumission des reçus numériques. | |
Array of objects non-empty Configuration des rappels basés sur les événements pour la réception des notifications. |
Responses
Response Schema: application/json
object | |
success | boolean |
message | string |
error | string or null |
Request samples
- Payload
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
- "fiscal_id": "YourCompanyFiscal_id",
- "name": "nameCompany",
- "receipts": true,
- "receipts_authentication": {
- "taxCode": "FHHWMF96L52D111B",
- "password": "1234567891****d",
- "pin": "1********4"
- "api_configurations": [
Response samples
- 200
- 409
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "name": "nameCompany",
- "receipts_authentication": {
- "taxCode": "FHHWMF96L52D111B"
- "api_configurations": [
- {
- "event": "receipt",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-credentials",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-retry",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-error",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- "receipts": true,
- "active": true,
- "create_timestamp": 1738318895,
- "id": "679ca42e**********016df7"
- "success": true,
- "message": "",
- "error": null
Récupérer une seule configuration informatique par numéro d'identification fiscale.
Ce point d'accès renvoie les détails d'une configuration individuelle, y compris les détails fiscaux et les paramètres de notification de l'API. Il permet aux entreprises de gérer leur intégration avec l'Agence du revenu et de surveiller les événements liés aux reçus
Authorizations:
path Parameters
fiscal_id required | string |
Responses
Response Schema: application/json
object | |
success | boolean |
message | string |
error | string or null |
Request samples
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
CURL *hnd = curl_easy_init(); curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET"); curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations/%7Bfiscal_id%7D"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN"); curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers); CURLcode ret = curl_easy_perform(hnd);
Response samples
- 200
- 404
- "data": {
- "fiscal_id": "YourCompanyFiscal_id2",
- "name": "nameCompany2",
- "receipts_authentication": {
- "taxCode": "FHHWMF96L52D111B"
- "api_configurations": [
- {
- "event": "receipt",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-credentials",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-retry",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-error",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- "receipts": true,
- "active": true,
- "create_timestamp": 1738318895,
- "id": "679ca42e**********016df7"
- "success": true,
- "message": "",
- "error": null
Mettre à jour une configuration informatique existante.
Ce service vous permet de modifier ou de mettre à jour les données d'authentification si elles ont expiré. Vous pouvez également mettre à jour les configurations de l'API. Si vous ne souhaitez plus recevoir de notifications pour un événement spécifique, mettez simplement le callback à null.
NB : Les informations d'identification dans receipts_authentication doivent être mises à jour tous les 90 jours (pour l'Agenzia delle entrate).
Authorizations:
path Parameters
fiscal_id required | string |
Request Body schema: application/json
receipts | boolean Indique si le système doit traiter les reçus numériques. |
object Informations d'authentification requises pour la soumission des reçus numériques. | |
Array of objects non-empty Configuration des rappels basés sur les événements pour la réception des notifications. |
Responses
Response Schema: application/json
object | |
success | boolean |
message | string |
error | string or null |
Request samples
- Payload
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
- "receipts": true,
- "receipts_authentication": {
- "taxCode": "FHHWMF96L52D111B",
- "password": "1234567891****d",
- "pin": "1********4"
- "api_configurations": [
Response samples
- 200
- 400
- 409
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "name": "nameCompany",
- "receipts_authentication": {
- "taxCode": "FHHWMF96L52D111B"
- "api_configurations": [
- {
- "event": "receipt",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-credentials",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-retry",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- {
- "event": "receipt-error",
- "callback": {
- "method": "JSON",
- "user_id": "",
- "username": "",
- "field": "data",
- "headers": { },
- "data": { },
- "retry": 0,
- "scope": null,
- "domain": null,
- "custom": null
- "receipts": true,
- "active": true,
- "create_timestamp": 1738318895,
- "id": "679ca42e**********016df7"
- "success": true,
- "message": "",
- "error": null
Supprimer une configuration informatique en fonction de l'identifiant fiscal.
Ce service permet de supprimer la configuration.
Note : La configuration ne peut être supprimée que si aucun reçu n'a été envoyé. Les reçus peuvent être envoyés via le point de terminaison POST /IT-receipts. Une fois les reçus envoyés, la configuration ne peut plus être supprimée.
Authorizations:
path Parameters
fiscal_id required | string |
Responses
Request samples
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
CURL *hnd = curl_easy_init(); curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE"); curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations/%7Bfiscal_id%7D"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN"); curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers); CURLcode ret = curl_easy_perform(hnd);
Response samples
- 200
- 404
- "data": "null",
- "success": true,
- "message": "Deleted configuration for id: YourCompanyFiscal_id",
- "error": null
Récupérer tous les récépissés informatiques.
Ce point d'accès permet de récupérer une liste de reçus informatiques et de les filtrer en fonction de divers paramètres. Les utilisateurs peuvent filtrer les résultats par fiscal_id, document_number, status, type, created_at, document_date et parent_receipt_id.
Les options de pagination incluent skip pour spécifier le nombre d'enregistrements à omettre et limit pour définir le nombre maximum d'enregistrements renvoyés (plafonné à 100).
fiscal_id, status et type supportent des valeurs multiples en les séparant par une virgule (par exemple, fiscal_id_1,fiscal_id_2).
status valeurs valides : new, retry, submitted, ready, failed, voided.
type valeurs valides : sale, return, void.
created_at et document_date doivent respecter le format AAAA-MM-JJ.
Ce point d'accès renvoie une réponse JSON structurée contenant les reçus correspondants.
Authorizations:
query Parameters
fiscal_id | string Filtrer les reçus par identifiant fiscal. |
document_number | string Filtrer les reçus par numéro de document. |
status | Array of strings Items Enum: "new" "retry" "submitted" "ready" "failed" "voided" Filtrer les reçus par statut. Plusieurs valeurs peuvent être fournies, séparées par des virgules. |
type | Array of strings Items Enum: "sale" "return" "void" Filtrer les reçus par type. Plusieurs valeurs peuvent être fournies, séparées par des virgules. |
created_at | string <date> Filtrer les reçus par date de création (format AAAA-MM-JJ). |
document_date | string <date> Filtrer les reçus par date de document (format AAAA-MM-JJ). |
parent_receipt_id | string Filtrer les reçus par l'ID du reçu parent. |
skip | integer >= 0 Nombre d'enregistrements à ignorer pour la pagination. |
limit | integer [ 1 .. 100 ] Nombre d'enregistrements à renvoyer (max. 100). |
Responses
Response Schema: application/json
Array of objects (ResponseReturnReceipt) |
Request samples
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
CURL *hnd = curl_easy_init(); curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET"); curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts?fiscal_id=SOME_STRING_VALUE&document_number=SOME_STRING_VALUE&status=SOME_ARRAY_VALUE&type=SOME_ARRAY_VALUE&created_at=SOME_STRING_VALUE&document_date=SOME_STRING_VALUE&parent_receipt_id=SOME_STRING_VALUE&skip=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN"); curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers); CURLcode ret = curl_easy_perform(hnd);
Response samples
- 200
- "data": [
- {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "id": "489432",
- "quantity": 11,
- "description": "test ultime",
- "gross_price": 10,
- "vat_rate": "22",
- "gross_discount": 0,
- "complimentary": true,
- "unit_price": 8.19672131,
- "return": 1,
- "taxable_amount": 8.19672131,
- "net_taxable_amount": 8.19672131,
- "vat_amount": 1.80327868,
- "total_amount": 10,
- "unit_discount": 0,
- "sku": "product1"
- "cash_payment_amount": 4.5,
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": null,
- "lottery_code": null,
- "created_at": "2025-01-31T16:29:52.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": 10,
- "document_number": "OPENAPI2025/0000-4712",
- "document_date": "2025-01-31T16:30:00.000Z",
- "transaction_id": "4712",
- "create_timestamp": 1738340991,
- "parent_receipt_id": "6as******************b52",
- "status": "ready",
- "type": "return",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 8.19672132,
- "total_uncollected_amount": 0,
- "total_vat_amount": 1.80327868,
- "update_timestamp": 1738341005,
- "id": "679ca42e**********016f18",
- "tags": [
- "es1",
- "es2"
- {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "id": "250652",
- "quantity": 11,
- "description": "test ultime",
- "gross_price": 10,
- "vat_rate": "22",
- "gross_discount": 0,
- "complimentary": true,
- "unit_price": 8.19672131,
- "return": 0,
- "taxable_amount": 90.16393442,
- "net_taxable_amount": 90.16393442,
- "vat_amount": 19.83606558,
- "total_amount": 110,
- "unit_discount": 0,
- "sku": "product2"
- "cash_payment_amount": 4.5,
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": "string",
- "lottery_code": null,
- "created_at": "2025-01-31T16:07:19.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": 110,
- "document_number": "OPENAPI2025/0000-4711",
- "document_date": "2025-01-31T16:07:26.000Z",
- "transaction_id": "4711",
- "create_timestamp": 1738339638,
- "status": "ready",
- "type": "sale",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 90.16393442,
- "total_uncollected_amount": 0,
- "total_vat_amount": 19.83606558,
- "update_timestamp": 1738341005,
- "id": "6as******************b52"
- {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "id": "200170",
- "quantity": 11,
- "description": "test ultime",
- "gross_price": 10,
- "vat_rate": "22",
- "gross_discount": 0,
- "complimentary": true,
- "unit_price": 8.19672131,
- "return": 0,
- "taxable_amount": 90.16393442,
- "net_taxable_amount": 90.16393442,
- "vat_amount": 19.83606558,
- "total_amount": 110,
- "unit_discount": 0,
- "sku": "product3"
- "cash_payment_amount": 4.5,
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": "string",
- "lottery_code": null,
- "created_at": "2025-01-31T14:08:20.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": 110,
- "document_number": "OPENAPI2025/0000-4706",
- "document_date": "2025-01-31T14:08:28.000Z",
- "transaction_id": "4706",
- "create_timestamp": 1738332500,
- "status": "ready",
- "type": "sale",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 90.16393442,
- "total_uncollected_amount": 0,
- "total_vat_amount": 19.83606558,
- "update_timestamp": 1738332518,
- "id": "671skdjapsj78*********23"
- "success": true,
- "message": "",
- "error": null
Créer un nouveau reçu.
Ce service vous permet de créer un reçu électronique intelligent pour une vente en ligne. Le Smart Receipt remplace l'émission d'un reçu par une caisse enregistreuse télématique et est idéal pour les transactions en ligne.
Contrairement à une facture électronique B2C, le Smart Electronic Receipt ne nécessite pas l'identification fiscale du client (codice fiscale). Il interagit directement avec le portail fiscal du gouvernement (cassetto fiscale) pour générer et stocker le reçu, agissant comme un proxy pour l'utilisateur.
Important : Avant d'utiliser ce service, vous devez mettre en place une configuration informatique qui représente la "Partita IVA" envoyant les reçus. Assurez-vous que le champ receipts : true est inclus dans le corps de la requête de la configuration informatique.
Environnement sandbox : Le sandbox simule la communication avec le portail de l'administration fiscale. Dans cet environnement, les identifiants des reçus intelligents seront simulés. Les identifiants réels de la configuration informatique de l'expéditeur ne sont pas nécessaires dans l'environnement sandbox, mais ils le sont pour l'environnement de production.
NB : Il est important de définir les événements suivants pour les rappels :
- receipt : Cet événement est déclenché lorsqu'un nouveau reçu est soumis et prêt
- receipt-credentials : Cet événement est déclenché lorsqu'il y a une mise à jour des informations d'identification
- receipt-retry:* Cet événement est déclenché lorsque la communication avec le portail de l'administration fiscale a échoué et que nous allons réessayer d'envoyer le reçu à nouveau
- receipt-error Cet événement est déclenché lorsque le portail de l'administration fiscale signale une erreur
- appointee *Cet événement est déclenché lorsque le processus de nomination pour les reçus intelligents a réussi
En effet, les détails du reçu seront mis à jour en fonction du type d'événement.
Avant d'envoyer un document au portail de l'administration fiscale, OpenaApi effectue quelques contrôles sur les données que vous avez envoyées. Si quelque chose ne va pas avec les données que vous avez envoyées
Authorizations:
Request Body schema: application/json
fiscal_id required | string Le numéro de TVA de l'entreprise qui délivre le reçu, sans le préfixe du pays. |
required | Array of objects Liste des éléments du reçu. |
invoice_issuing | boolean Drapeau indiquant si une facture sera émise. |
services_uncollected_amount | number Montant non perçu en EUR pour les services. |
goods_uncollected_amount | number Montant non perçu en EUR pour les marchandises livrées. |
electronic_payment_amount | number Montant payé électroniquement en EUR. |
ticket_restaurant_payment_amount | number Montant payé à l'aide du ticket restaurant en EUR. |
ticket_restaurant_quantity | integer Nombre de titres-restaurant utilisés. |
discount | number La réduction est appliquée au moment du paiement mais ne modifie pas le montant imposable. |
lottery_code | string Code de loterie permettant au client de participer à la loterie "Lotteria degli scontrini". Le "lottery_code" doit être composé de 8 caractères alphanumériques. Le code de loterie ne peut pas être utilisé si le montant total est inférieur à 1,00 EUR ou si le paiement n'est pas entièrement électronique |
linked_receipt | string Référence à un reçu lié, le cas échéant. |
cash_payment_amount required | number Montant payé en espèces en EUR. |
tags | Array of objects Vous pouvez insérer les détails de votre reçu. |
Responses
Response Schema: application/json
object | |
success | boolean Indique si l'opération a réussi. |
message | string Message supplémentaire relatif à l'opération. |
error | string or null Message d'erreur le cas échéant. |
Callbacks
Request samples
- Payload
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "quantity": 11,
- "description": "test",
- "unit_price": 10,
- "vat_rate_code": "22",
- "discount": 0,
- "complimentary": true,
- "sku": "product1"
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "lottery_code": "1a3v5g7f",
- "linked_receipt": "string",
- "cash_payment_amount": 4.5,
- "tags": [
- [
- "store1",
- "store2"
Response samples
- 200
- 400
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "quantity": 11,
- "description": "test ultimate",
- "unit_price": 10,
- "vat_rate_code": "22",
- "complimentary": true,
- "discount": 0,
- "sku": "product1"
- "cash_payment_amount": 4.5,
- "id": "679cd95***************23",
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": "string",
- "lottery_code": null,
- "created_at": "2025-01-31T14:08:20.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": 0,
- "document_number": "",
- "document_date": null,
- "transaction_id": null,
- "create_timestamp": 1738332500,
- "status": "new",
- "type": "sale",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 0,
- "total_uncollected_amount": 0,
- "total_vat_amount": 0,
- "update_timestamp": 1738341000,
- "tags": [
- [
- "store1",
- "store2"
- "success": true,
- "message": "",
- "error": null
Callback payload samples
Dans le rappel, les différents types et états de l'accusé de réception seront renvoyés. Il s'agit de la réponse lorsque le récépissé a été émis avec succès et est prêt.
- "data": {
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "id": "200170",
- "quantity": 10,
- "description": "produit",
- "gross_price": 10,
- "vat_rate": "22",
- "gross_discount": 0,
- "complimentary": true,
- "unit_price": 8.19672131,
- "return": 0,
- "taxable_amount": 90.16393442,
- "net_taxable_amount": 90.16393442,
- "vat_amount": 19.83606558,
- "total_amount": 110,
- "unit_discount": 0
- "cash_payment_amount": 100,
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": "string",
- "lottery_code": null,
- "created_at": "2025-01-31T14:08:20.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": 110,
- "document_number": "OPENAPI2025/0000-4706",
- "document_date": "2025-01-31T14:08:28.000Z",
- "transaction_id": "4706",
- "create_timestamp": 1738332500,
- "status": "ready",
- "type": "sale",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 90.16393442,
- "total_uncollected_amount": 0,
- "total_vat_amount": 19.83606558,
- "update_timestamp": 1738332518,
- "id": "679c**********1111111111"
- "custom": null
Récupérer un seul reçu par ID.
Récupère les détails d'un seul reçu en utilisant son identifiant unique. L'identifiant du reçu doit être fourni dans le chemin d'accès à la demande.
Authorizations:
path Parameters
id required | string Example: 679cd95***************23 |
Responses
Response Schema: application/json
object |
Request samples
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
CURL *hnd = curl_easy_init(); curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET"); curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts/%7Bid%7D"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN"); curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers); CURLcode ret = curl_easy_perform(hnd);
Response samples
- 200
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "id": "'200170'",
- "quantity": 10,
- "description": "product",
- "gross_price": 10,
- "vat_rate": "'22'",
- "gross_discount": 0,
- "complimentary": true,
- "unit_price": 8.19672131,
- "return": 0,
- "taxable_amount": 90.16393442,
- "net_taxable_amount": 90.16393442,
- "vat_amount": 19.83606558,
- "total_amount": 110,
- "unit_discount": 0,
- "sku": "product1"
- "cash_payment_amount": 100,
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": "string",
- "lottery_code": null,
- "created_at": "2025-01-31T14:08:20.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": 110,
- "document_number": "OPENAPI2025/0000-4706",
- "document_date": "2025-01-31T14:08:28.000Z",
- "transaction_id": "4706",
- "create_timestamp": 1738332500,
- "status": "ready",
- "type": "sale",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 90.16393442,
- "total_uncollected_amount": 0,
- "total_vat_amount": 19.83606558,
- "update_timestamp": 1738332518,
- "id": "679c**********1111111111"
Renvoyer un ou plusieurs articles d'un reçu.
Ce point d'accès permet de renvoyer un ou plusieurs éléments d'un reçu spécifique. L'identifiant du reçu est fourni dans le chemin d'accès, tandis que les articles à renvoyer sont spécifiés dans le corps de la requête avec leurs identifiants et quantités respectifs.
NB : La réponse de ce point d'accès est un nouveau reçu lié au précédent. Une nouvelle clé, parent_receipt_id, est définie, qui sera remplie avec l'ID du reçu à partir duquel les retours sont effectués.
Authorizations:
path Parameters
id required | string Example: 679c***6d00d0***b23 Identifiant unique du reçu à mettre à jour. |
Request Body schema: application/json
Array of objects Liste des objets à restituer. |
Responses
Response Schema: application/json
object |
Callbacks
Request samples
- Payload
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
- "items": [
- {
- "id": "374813",
- "quantity": 2
Response samples
- 200
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- { }
- "cash_payment_amount": 0,
- "id": "112ss95***************2",
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": null,
- "lottery_code": null,
- "created_at": "2025-01-31T16:29:52.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": null,
- "document_number": "",
- "document_date": null,
- "transaction_id": null,
- "create_timestamp": 1738340991,
- "parent_receipt_id": "679cf5377be****b540a2b52",
- "status": "new",
- "type": "return",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 0,
- "total_uncollected_amount": 0,
- "total_vat_amount": 0,
- "update_timestamp": 1738341000,
- "tags": [
- "store1",
- "store2"
Callback payload samples
Dans le rappel, les différents types et états de l'accusé de réception seront renvoyés. Il s'agit de la réponse lorsque le récépissé a été émis avec succès et est prêt.
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "id": "250652",
- "quantity": 1,
- "description": "produit",
- "gross_price": 10,
- "vat_rate": "22",
- "gross_discount": 0,
- "complimentary": true,
- "unit_price": 8.19672131,
- "return": 1,
- "taxable_amount": 90.16393442,
- "net_taxable_amount": 90.16393442,
- "vat_amount": 19.83606558,
- "total_amount": 110,
- "unit_discount": 0
- "cash_payment_amount": 0,
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": "string",
- "lottery_code": null,
- "created_at": "2025-01-31T16:07:19.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": 110,
- "document_number": "OPENAPI2025/0000-4711",
- "document_date": "2025-01-31T16:07:26.000Z",
- "transaction_id": "4711",
- "create_timestamp": 1738339638,
- "status": "ready",
- "type": "sale",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 90.16393442,
- "total_uncollected_amount": 0,
- "total_vat_amount": 19.83606558,
- "update_timestamp": 1738341005,
- "id": "679cf5377be****b540a2b52"
- "custom": null
Supprimer un reçu par ID.
Ce point d'accès permet d'annuler un reçu dans les 24 heures suivant sa soumission. Le système génère un nouveau reçu annulé lié au reçu original par l'intermédiaire du paramètre parent_receipt_id.
Le reçu annulé reflétera l'annulation de la transaction originale tout en maintenant la traçabilité.
En cas de succès, la réponse comprendra les détails du nouveau reçu annulé.
Authorizations:
path Parameters
id required | string Example: 6a9**************d077b23 |
Responses
Response Schema: application/json
object | |
message | string Message de confirmation pour le reçu annulé. |
success | boolean Indique si l'opération d'annulation a réussi. |
error | string or null Message d'erreur en cas d'échec, null en cas de succès. |
Callbacks
Request samples
- C + Libcurl
- Csharp + Restsharp
- Go + Native
- Java + Okhttp
- Java + Unirest
- Javascript + Jquery
- Javascript + Xhr
- Node + Native
- Node + Request
- Node + Unirest
- Objc + Nsurlsession
- Ocaml + Cohttp
- Php + Curl
- Php + Http1
- Php + Http2
- Python + Python3
- Python + Requests
- Ruby + Native
- Shell + Curl
- Shell + Httpie
- Shell + Wget
- Swift + Nsurlsession
CURL *hnd = curl_easy_init(); curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE"); curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts/%7Bid%7D"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN"); curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers); CURLcode ret = curl_easy_perform(hnd);
Response samples
- 200
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": {
- "id": "'200170'",
- "quantity": 10,
- "description": "product",
- "gross_price": 10,
- "vat_rate": "'22'",
- "gross_discount": 0,
- "complimentary": true,
- "unit_price": 8.19672131,
- "return": 0,
- "taxable_amount": 90.16393442,
- "net_taxable_amount": 90.16393442,
- "vat_amount": 19.83606558,
- "total_amount": 110,
- "unit_discount": 0,
- "sku": "product1"
- "cash_payment_amount": 4.5,
- "id": "6b7****************03b8d2",
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": null,
- "lottery_code": null,
- "created_at": "2025-01-31T16:29:52.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": null,
- "document_number": "",
- "document_date": null,
- "transaction_id": null,
- "create_timestamp": 1738340991,
- "parent_receipt_id": "6a9**************d077b23",
- "status": "new",
- "type": "return",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 0,
- "total_uncollected_amount": 0,
- "total_vat_amount": 0,
- "update_timestamp": 1738341000
- "message": "voided receipt: 6a9**************d077b23",
- "success": true,
- "error": "nulll"
Callback payload samples
Dans le rappel, les différents types et états du reçu seront renvoyés. Il s'agit de la réponse lorsque le reçu a été annulé avec succès.
- "data": {
- "fiscal_id": "YourCompanyFiscal_id",
- "items": [
- {
- "id": "250652",
- "quantity": 11,
- "description": "produit",
- "gross_price": 10,
- "vat_rate": "22",
- "gross_discount": 0,
- "complimentary": true,
- "unit_price": 8.19672131,
- "return": 0,
- "taxable_amount": 90.16393442,
- "net_taxable_amount": 90.16393442,
- "vat_amount": 19.83606558,
- "total_amount": 110,
- "unit_discount": 0
- "cash_payment_amount": 4.5,
- "invoice_issuing": false,
- "services_uncollected_amount": 0,
- "goods_uncollected_amount": 0,
- "electronic_payment_amount": 0,
- "ticket_restaurant_payment_amount": 0,
- "ticket_restaurant_quantity": 0,
- "discount": 0,
- "linked_receipt": "string",
- "lottery_code": null,
- "created_at": "2025-01-31T16:07:19.000Z",
- "error_message": null,
- "error_code": null,
- "total_amount": 110,
- "document_number": "OPENAPI2025/0000-4711",
- "document_date": "2025-01-31T16:07:26.000Z",
- "transaction_id": "4711",
- "create_timestamp": 1738339638,
- "status": "voided",
- "type": "sale",
- "deductible_amount": 0,
- "total_discount": 0,
- "total_gross_discount": 0,
- "total_taxable_amount": 90.16393442,
- "total_uncollected_amount": 0,
- "total_vat_amount": 19.83606558,
- "update_timestamp": 1738341005,
- "id": "679cf5377be****b540a2b52"
- "custom": null