Invoice

  1. Home
  2. Libreria API
  3. Invoice
Invia Scontrini Elettronici all'Agenzia delle Entrate in modo semplice, veloce e con elevati standard di sicurezza.

Automatizza l’invio dei documenti commerciali tramite API in tempo reale.

Tutte le informazioni di cui hai bisogno

Qui trovi qualche consiglio da prendere in considerazione per approcciare a questa API. Se preferisci forniamo esempi di codice, documentazione in OAS3, la possibilità di provare l'API dal vivo con la Swagger UI oppure importare l'intera collezione in Postman. Offriamo inoltre un ambiente di Sandbox dove puoi sperimentare tutte le API gratuitamente.

Utili consigli per iniziare con Invoice

Prendi il token nell'apposita sezione prima di cominciare.

Usa lo strumento online o generalo via API. Imposta una data di scadenza e aggiungi una serie di Scopes per limitare le possibli azioni permesse al token.
Approfondisci Oauth Gestisci i tokens

Configura l'azienda

Creazione di una nuova configurazione
POST /IT-configurations
Questo endpoint permette di creare una nuova configurazione per l'azienda. È possibile anche specificare le credenziali e gli URL di callback per ricevere notifiche sugli scontrini.

Visualizzazione delle configurazioni
GET /IT-configurations
Questo endpoint consente di ottenere l'elenco delle configurazioni registrate per l'azienda, comprese le credenziali e le callback impostate.

Aggiornamento di una configurazione esistente
PATCH /IT-configurations/{fiscal_id}
Questo endpoint consente di aggiornare le credenziali, aggiungere opzioni e modificare gli URL di callback associati a una configurazione esistente.

Eliminazione di una configurazione
DELETE /IT-configurations/{fiscal_id}
Questo endpoint permette di eliminare una configurazione. Nota: se sono già stati inviati scontrini con questa configurazione, non sarà più possibile eliminarla.

Gestione degli scontrini

Utilizza i seguenti endpoint per gestire gli scontrini elettronici:

Creazione di un nuovo scontrino
POST /IT-receipts
Questo endpoint permette di inviare un nuovo scontrino elettronico. Il sistema genererà un id per identificare univocamente lo scontrino e invierà una notifica all'URL configurato.

Registrazione di un reso
PATCH /IT-receipts/{id}
Se un cliente restituisce un prodotto, questo endpoint consente di aggiornare lo scontrino esistente e generarne uno per registrare il reso.

Annullamento di uno scontrino
DELETE /IT-receipts/{id}
Questo endpoint consente di annullare uno scontrino precedentemente inviato, generando uno scontrino di annullamento. Il sistema invierà una notifica di annullamento all'URL configurato.

Visualizzazione degli scontrini
GET /IT-receipts
Questo endpoint restituisce l'elenco degli scontrini registrati, con la possibilità di filtrare per data, importo o altri parametri.
API docs by Redocly

Invoice (1.0.0)

URL: https://openapi.it/en/support License: Apache 2.0 Terms of Service

API per la gestione delle configurazioni delle fatture e delle ricevute digitali nel rispetto della normativa fiscale. Questo servizio consente alle aziende di configurare le impostazioni di fatturazione e gestire le ricevute, garantendo la conformità agli standard dell'Agenzia delle Entrate per la fatturazione elettronica e la trasmissione delle ricevute digitali. Supporta lo scambio sicuro di dati, l'invio di ricevute in tempo reale e l'aggiornamento della configurazione per i requisiti di rendicontazione fiscale.

IMPORTANTE: Si ricorda che non è possibile inviare ricevute tra le 23:55 e le 00:00 (fuso orario italiano) all'Agenzia delle Entrate. Per questo motivo, tutte le ricevute inviate in questa fascia oraria saranno inviate nel primo momento disponibile, ovvero nei primi minuti del nuovo giorno.

NB: È necessario abilitare il codice fiscale inserito nella configurazione alla voce receipts_authentication-taxCode per l'invio delle ricevute. Seguire la procedura descritta in questo link.

Prima volta qui? Generare un nuovo token di accesso

IT-configuration

Gestire le configurazioni aziendali.

Recuperare tutte le configurazioni IT.

Recupera tutte le configurazioni IT associate all'utente. Questo endpoint restituisce un elenco di configurazioni, compresi i dettagli fiscali e le impostazioni di notifica API. Consente alle aziende di gestire l'integrazione con l'autorità fiscale e di monitorare gli eventi relativi alle ricevute.

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
}

Creare una nuova configurazione IT.

La configurazione IT è uno strumento utilizzato per impostare e gestire i dati aziendali per la propria attività. Funziona come un'entità che rappresenta un'azienda gestita dal proprio account. Attraverso questa configurazione è possibile personalizzare diverse impostazioni

IMPORTANTE: Per ricevere le notifiche, è necessario inserire le api_configurazioni e impostare l'evento come indicato negli schemi. Sarà sempre possibile aggiornare i dati con la configurazione PATCH IT

Per l'invio di ricevute, è necessario abilitare l'opzione receipts a true.

Per impostazione predefinita, saranno tutte impostate su false.

Sarà possibile configurare gratuitamente fino a 10 aziende al giorno, successivamente verrà applicato il prezzo indicato

Authorizations:
bearerAuth
Request Body schema: application/json
fiscal_id
required
string

L'identificativo fiscale univoco (partita IVA o codice fiscale) dell'azienda registrata presso l'Agenzia delle Entrate.

name
required
string

Il nome della società o dell'ente associato all'ID fiscale.

email
required
string <email>

L'indirizzo e-mail utilizzato per le comunicazioni e le notifiche. Non può essere modificato dopo la creazione della configurazione.

receipts
boolean

Indica se il sistema deve gestire le ricevute digitali.

object

Credenziali di autenticazione richieste per l'invio della ricevuta digitale.

Array of objects non-empty

Configurazione di callback basati su eventi per la ricezione di notifiche.

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
}

Recuperare una singola configurazione IT in base al codice fiscale.

Questo endpoint restituisce i dettagli di una configurazione individuale, compresi i dettagli fiscali e le impostazioni di notifica API. Consente alle aziende di gestire l'integrazione con l'Agenzia delle entrate e di monitorare gli eventi relativi alle ricevute

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
}

Aggiornare una configurazione IT esistente.

Questo servizio consente di modificare o aggiornare i dati di autenticazione nel caso in cui siano scaduti. È anche possibile aggiornare le configurazioni dell'API. Se non si desidera più ricevere notifiche per un evento specifico, è sufficiente impostare il callback a null.

NB: Le credenziali nella ricezione_autenticazione devono essere aggiornate ogni 90 giorni (per l'Agenzia delle entrate).

Authorizations:
bearerAuth
path Parameters
fiscal_id
required
string
Request Body schema: application/json
receipts
boolean

Indica se il sistema deve gestire le ricevute digitali.

object

Credenziali di autenticazione richieste per l'invio della ricevuta digitale.

Array of objects non-empty

Configurazione di callback basati su eventi per la ricezione di notifiche.

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
}

Eliminare una configurazione IT in base al codice fiscale.

Questo servizio consente di eliminare la configurazione.

Nota: La configurazione può essere eliminata solo se non sono state inviate ricevute. Le ricevute possono essere inviate tramite l'endpoint POST /IT-receipts. Una volta inviate le ricevute, la configurazione non può essere eliminata.

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

Gestire l'elaborazione delle ricevute.

Recuperare tutte le ricevute IT.

Questo endpoint recupera un elenco di ricevute IT, consentendo di filtrare in base a vari parametri. Gli utenti possono filtrare i risultati in base a ID fiscale, numero_documento, stato, type, data_creazione, data_documento e ID_receipt_genitore.

Le opzioni di paginazione includono il salto per specificare il numero di record da omettere e il limite per definire il numero massimo di record restituiti (con un tetto massimo di 100).

tax_id, status e type supportano valori multipli separandoli con una virgola (ad esempio, fiscal_id_1,fiscal_id_2).

status valori validi: nuovo, riprovato, inviato, pronto, fallito, annullato.

type valori validi: sale, return, void.

created_at e document_date devono seguire il formato YYYY-MM-DD.

Questo endpoint restituisce una risposta JSON strutturata contenente le ricevute corrispondenti.

Authorizations:
bearerAuth
query Parameters
fiscal_id
string

Filtrare le ricevute per ID fiscale.

document_number
string

Filtrare le ricevute per numero di documento.

status
Array of strings
Items Enum: "new" "retry" "submitted" "ready" "failed" "voided"

Filtrare le ricevute in base allo stato. È possibile fornire più valori, separati da virgole.

type
Array of strings
Items Enum: "sale" "return" "void"

Filtrare le ricevute per tipo. È possibile fornire più valori, separati da virgole.

created_at
string <date>

Filtrare le ricevute per data di creazione (formato AAAA-MM-GG).

document_date
string <date>

Filtrare le ricevute per data del documento (formato AAAA-MM-GG).

parent_receipt_id
string

Filtrare le ricevute in base all'ID della ricevuta del genitore.

skip
integer >= 0

Numero di record da saltare per la paginazione.

limit
integer [ 1 .. 100 ]

Numero di record da restituire (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
}

Creare una nuova ricevuta.

Questo servizio consente di creare una Smart Electronic Receipt per una vendita online. La Smart Receipt sostituisce l'emissione di una ricevuta attraverso un registratore di cassa telematico ed è ideale per le transazioni online.

A differenza della fattura elettronica B2C, la Smart Electronic Receipt non richiede il codice fiscale del cliente. Interagisce direttamente con il portale fiscale dello Stato (cassetto fiscale) per generare e conservare lo scontrino, agendo come proxy per l'utente.

Importante: Prima di utilizzare questo servizio, è necessario impostare una configurazione informatica che rappresenti la "Partita IVA" che invia le ricevute. Assicurarsi che il campo ricevute: true sia incluso nel corpo della richiesta di configurazione IT.

Ambiente sandbox: Il sandbox simula la comunicazione con il portale dell'Agenzia delle Entrate. In questo ambiente verranno simulati gli identificativi delle Smart Receipt. Le credenziali reali per la configurazione IT del mittente non sono necessarie nell'ambiente sandbox, mentre sono necessarie per l'ambiente di produzione.

NB: È importante impostare i seguenti eventi per i callback:

  • receipt: Questo evento viene attivato quando una nuova ricevuta viene inviata e pronta
  • ricevuta-credenziali: Questo evento viene attivato quando ci sono aggiornamenti sulle credenziali
  • receipt-retry:Questo evento viene attivato quando la comunicazione con il portale dell'Agenzia delle Entrate non è andata a buon fine e si tenterà di inviare nuovamente la ricevuta
  • questo evento viene attivato quando il portale dell'Agenzia delle Entrate segnala un errore*
  • appointee Questo evento viene generato quando il processo di assegnazione di una nomina per le ricevute intelligenti è riuscito

Questo perché i dettagli della ricevuta saranno aggiornati in base al type dell'evento.

Prima di inviare un documento al portale dell'Agenzia delle Entrate, OpenaApi esegue alcuni controlli sui dati inviati. Se c'è qualcosa di sbagliato nei dati inviati

Authorizations:
bearerAuth
Request Body schema: application/json
fiscal_id
required
string

Il numero di partita IVA dell'azienda che emette la ricevuta, senza il prefisso del paese.

required
Array of objects

Elenco degli articoli della ricevuta.

invoice_issuing
boolean

Flag che indica se verrà emessa una fattura.

services_uncollected_amount
number

Importo non riscosso in euro per servizi.

goods_uncollected_amount
number

Importo non riscosso in euro per le merci consegnate.

electronic_payment_amount
number

Importo pagato elettronicamente in EUR.

ticket_restaurant_payment_amount
number

Importo pagato con il ticket restaurant in EUR.

ticket_restaurant_quantity
integer

Numero di buoni pasto utilizzati.

discount
number

Lo sconto viene applicato al momento del pagamento ma non modifica l'importo imponibile.

lottery_code
string

Codice della lotteria che consente al cliente di partecipare alla lotteria degli scontrini. Il codice della lotteria deve essere composto da 8 caratteri alfanumerici. Il codice della lotteria non può essere utilizzato se l'importo totale è inferiore a 1,00 euro o se il pagamento non è stato completamente elettronico"

linked_receipt
string

Riferimento a una ricevuta collegata, se applicabile.

cash_payment_amount
required
number

Importo pagato in contanti in euro.

tags
Array of objects

È possibile inserire i dettagli della ricevuta.

Responses

Response Schema: application/json
object
success
boolean

Indica se l'operazione è andata a buon fine.

message
string

Messaggio aggiuntivo relativo all'operazione.

error
string or null

Messaggio di errore, se applicabile.

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

Nel callback, verranno restituiti i vari tipi e stati della ricevuta. Questa è la risposta in cui la ricevuta è stata emessa con successo ed è pronta.

{
  • "data": {
    }
}

Recupera una singola ricevuta per ID.

Recupera i dettagli di una singola ricevuta utilizzando il suo identificativo univoco. L'ID della ricevuta deve essere fornito nel percorso della richiesta.

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

Restituire uno o più articoli da uno scontrino.

Questo endpoint consente di restituire uno o più articoli di uno specifico scontrino. L'ID della ricevuta è fornito nel percorso, mentre gli articoli da restituire sono specificati nel corpo della richiesta con i rispettivi ID e quantità.

NB: La risposta di questo endpoint è una nuova ricevuta collegata alla precedente. Viene impostata una nuova chiave, parent_receipt_id, che sarà popolata con l'ID della ricevuta da cui vengono effettuati i resi.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 679c***6d00d0***b23

Identificatore univoco della ricevuta da aggiornare.

Request Body schema: application/json
Array of objects

Elenco degli articoli da restituire.

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

Nel callback, verranno restituiti i vari tipi e stati della ricevuta. Questa è la risposta in cui la ricevuta è stata emessa con successo ed è pronta.

{
  • "data": {
    },
  • "custom": null
}

Eliminare una ricevuta per ID.

Questo endpoint consente di annullare una ricevuta entro 24 ore dalla sua presentazione. Il sistema genererà una nuova ricevuta di annullamento collegata a quella originale attraverso il parametro parent_receipt_id.

La ricevuta di annullamento rifletterà l'annullamento della transazione originale mantenendo la tracciabilità.

In caso di successo, la risposta includerà i dettagli della nuova ricevuta di annullamento creata.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 6a9**************d077b23

Responses

Response Schema: application/json
object
message
string

Messaggio di conferma per la ricevuta annullata.

success
boolean

Indica se l'operazione di annullamento è andata a buon fine.

error
string or null

Messaggio di errore in caso di fallimento, nullo in caso di successo.

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

Nel callback vengono restituiti i vari tipi e stati della ricevuta. Questa è la risposta se la ricevuta è stata annullata con successo.

{
  • "data": {
    },
  • "custom": null
}
Web Service Revision: 2.0.0