Invoice

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.

Conseils utiles pour commencer Invoice

Obtenir le Token dans la section appropriée avant de commencer.

Utilisez l'outil en ligne ou générez-le via l'API. Définissez la date d'expiration, un nom utile et ajoutez maintenant un ensemble d'étendues pour limiter les actions possibles que votre jeton peut effectuer.

Gestion de l'entreprise

Créer une nouvelle configuration
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

Utilisez les endpoints suivants pour gérer les reçus électroniques :

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.

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).

IT-configuration

Gérer les configurations de l'entreprise.

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:
bearerAuth

Responses

Response Schema: application/json
Array of objects (ITConfigurationResponse)

Request samples

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

Content type
application/json
{
  • "data": [
    ],
  • "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:
bearerAuth
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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "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:
bearerAuth
path Parameters
fiscal_id
required
string

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string or null

Request samples

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

Content type
application/json
{
  • "data": {
    },
  • "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:
bearerAuth
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

Content type
application/json
{
  • "receipts": true,
  • "receipts_authentication": {
    },
  • "api_configurations": []
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "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:
bearerAuth
path Parameters
fiscal_id
required
string

Responses

Request samples

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

Content type
application/json
{
  • "data": "null",
  • "success": true,
  • "message": "Deleted configuration for id: YourCompanyFiscal_id",
  • "error": null
}

IT-receipt

Traiter les accusés de réception.

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:
bearerAuth
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

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

Content type
application/json
{
  • "data": [
    ],
  • "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:
bearerAuth
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

Content type
application/json
{
  • "fiscal_id": "YourCompanyFiscal_id",
  • "items": [
    ],
  • "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": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Callback payload samples

Callback
POST: {your_url}
Content type
application/json

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": {
    }
}

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:
bearerAuth
path Parameters
id
required
string
Example: 679cd95***************23

Responses

Response Schema: application/json
object

Request samples

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

Content type
application/json
{
  • "data": {
    }
}

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:
bearerAuth
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

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Callback payload samples

Callback
POST: postReceiptCallback
Content type
application/json
Example

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": {
    },
  • "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:
bearerAuth
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

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

Content type
application/json
{
  • "data": {
    },
  • "message": "voided receipt: 6a9**************d077b23",
  • "success": true,
  • "error": "nulll"
}

Callback payload samples

Callback
POST: postReceiptCallback
Content type
application/json
Example

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": {
    },
  • "custom": null
}