Focus
API per l’invio dei corrispettivi: guida per sviluppatori
L’invio telematico dei corrispettivi è oggi un passaggio obbligato per tutte le realtà che operano nel retail e nei servizi. L’integrazione con i sistemi dell’Agenzia delle Entrate richiede però precisione, affidabilità e una gestione attenta delle casistiche operative. Inoltre, è necessario che le soluzioni individuate non rallentino i flussi aziendali e che non rappresentino un costo eccessivo. In quest’ottica, le nostre API rappresentano uno strumento efficace per automatizzare il processo e integrarlo nei propri sistemi. In questa guida vediamo come funziona l’API per l’invio dei corrispettivi sviluppata da noi di A-Cube. Nel corso dei paragrafi, vedremo quali chiamate API effettuare per ogni azione.
Nuove regole per inviare i corrispettivi: moduli e modelli
L'invio dei corrispettivi tramite API è regolamentato dall'Agenzia delle Entrate. Sono ammesse infatti soluzioni di questo tipo purché rispettino le specifiche tecniche e di controllo e abbiano ottenuto le dovute certificazioni. Si tratta dei cosiddetti moduli PEM e PEL, che lavorano in modo interconnesso per creare un flusso di dati sicuro e inalterabile. In particolare:
il PEM comunica con il registratore di cassa o il dispositivo elettronico del commerciante. Acquisisce i dati per ogni transazione e crea un “pacchetto di acquisizione” sigillato applicando una prima firma elettronica. In questo modo, garantisce l'integrità e l'autenticità dei dati fin dal primo istante.
Il PEL riceve i pacchetti di acquisizione sigillati dal PEM, verifica la firma del pacchetto e la salva in un registro protetto e permanente che non può essere alterato o cancellato. Aggrega quindi i dati per la trasmissione finale all'Agenzia delle Entrate.
La piattaforma sviluppata da A-Cube contiene entrambi i moduli. A seconda del ruolo che il partner intende ricoprire, è possibile optare per la modalità:
partner come produttore;
A-Cube come produttore e partner come erogatore;
A-Cube come produttore ed erogatore.
Si tratta di tre possibili modelli di collaborazione indirizzati a produttori, erogatori ed esercenti. La soluzione A-Cube per i corrispettivi è progettata per adattarsi a diversi livelli di maturità tecnologica e complessità applicativa.
Integrazione dell’API per l’invio dei corrispettivi: come iniziare
Come fare per integrare la soluzione A-Cube per i corrispettivi nei sistemi esistenti? In qualità di fornitore, bisogna registrarsi per creare un account sulla piattaforma A-Cube e poi autenticarsi come fornitore seguendo le indicazioni della sezione Autenticazione.
A questo punto, è necessario creare un nuovo conto commerciante per registrare transazioni, generare ricevute per i clienti e memorizzare e trasmettere i dati fiscali. Per farlo, bisogna utilizzare il seguente endpoint API:
POST https://ereceipts-it-sandbox.acubeapi.com/mf2/merchant
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Supplier JWT Token>
{
"vat_number": "12345678901",
"address": {
"street_address": "street name",
"street_number": "xx",
"zip_code": "00000",
"city": "City",
"province": "XX"
},
"business_name": "business name",
"email": "merchant@example.com",
"password": "MerchantP4$$w0rd"
}
Response 201
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"vat_number": "12345678901",
"fiscal_code": "XXXXXX00A00X000X",
"address": {
"street_address": "street name",
"street_number": "xx",
"zip_code": "00000",
"city": "City",
"province": "XX"
},
"business_name": "foo bar",
"first_name": "first name",
"last_name": "last name",
"email": "foobar@example.com"
}
A questo punto è possibile creare un nuovo PEM utilizzando il seguente endpoint API:
POST https://ereceipts-it-sandbox.acubeapi.com/mf2/pems
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Supplier JWT Token>
{
"merchant_uuid": "836b70aa-239b-4c8d-b654-0f5a9a4d133a"
}
Response 201
{
"serial_number": "A2F4-000001",
"registration_key": "527462046048ce9bc72e64d77b975fdafd448825"
}
L'indirizzo fisico del PEM viene ereditato dall'indirizzo del commerciante creato nel passaggio precedente. Servirà per attivare il PEM nel passaggio successivo.
API A-Cube: autenticazione e attivazione del PEM
A questo punto, con il profilo commerciante precedentemente creato è possibile accedere e ottenere un token JWT per commercianti.
POST https://common-sandbox.api.acubeapi.com/login
Content-Type: application/json
Accept: application/json
{
"email": "merchant@example.com",
"password": "merchant password"
}
Response 200
{
"token": "Merchant JWT Token"
}
Ora è possibile attivare il PEM utilizzando la chiave di registrazione ottenuta al momento della creazione del PEM. In quel passaggio, si riceve il numero di serie del PEM che viene utilizzato nell'URL dell'endpoint API per identificare il modulo.
POST https://ereceipts-it-sandbox.acubeapi.com/mf1/pems/A2F4-000001/activation/
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Merchant JWT Token>
{
"registration_key": "527462046048ce9bc72e64d77b975fdafd448825"
}
Response 202
Ora si può creare un nuovo registratore di cassa per il PEM. Questo deve essere autenticato con MF1 utilizzando un mTLScertificato (TLS reciproco). Per attivare la licenza per il registratore di cassa e generare un nuovo mTLScertificato tramite l’API per l’invio dei corrispettivi bisogna eseguire la seguente chiamata API.
POST https://ereceipts-it-sandbox.acubeapi.com/mf1/cash-register
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Merchant JWT Token>
{
"pem_serial_number": "A2F4-000001",
"name": "Cash register first floor"
}
Response 201
{
"uuid": "f69023bf-ee89-4d66-a7e7-9a65e4f365da",
"pem_serial_number": "A2F4-000001",
"name": "Cash register first floor",
"mtls_certificate": "----- BEGIN CERTIFICATE -----....",
"private_key": "-----BEGIN RSA PRIVATE KEY-----..."
}
Questo certificato viene utilizzato per autenticare il registratore di cassa presso l'API MF1 e per identificarlo nel sistema. A questo punto si può archiviare il contenuto dei campi mtls_certificatee private_key nella memoria del registratore di cassa.
Quando si salvano il certificato e la chiave privata in file, i valori ricevuti conterranno la sequenza di caratteri speciali "\n" che rappresentano le interruzioni di riga. Prima di scriverli su disco, assicurarsi di sostituire ogni "\n" interruzione di riga con una vera interruzione di riga. Questo garantisce che il certificato e la chiave vengano memorizzati nel formato multilinea corretto previsto dal sistema.
Inviare e recuperare ricevute tramite l’API A-Cube
Dopo aver seguito i passaggi precedenti, è possibile connettersi utilizzando il mTLScertificato per emettere una ricevuta. È necessario configurare il client API in modo che utilizzi il mTLScertificato generato precedentemente. Tutte le comunicazioni con MF1 utilizzando il mTLScertificato devono essere effettuate sulla porta444 (ovvero https://ereceipts-it-sandbox.acubeapi.com:444).
Nella sezione dedicata agli sviluppatori sono disponibili alcuni esempi di come individuare una ricevuta di invio del mTLS certificato utilizzando diversi linguaggi di programmazione. Tra questi: Piton,e JavaScript, Bash e PHP.
La risposta che si riceve è la seguente:
Response 201
{
"uuid": "39f65b28-b1fa-401b-ad58-0addcaef7162",
"type": "sale",
"total_amount": "244",
"document_number": "0001-0001",
"document_datetime": "2025-07-22T09:45:22",
"parent_receipt_uuid": null,
"is_voidable": true,
"is_returnable": true,
"html_url": "url/to/html",
"pdf_url": "url/to/pdf"
}
A questo punto è possibile interrogare l'API per l’invio dei corrispettivi per ottenere i dati della ricevuta oppure ottenere il PDF inviando la stessa richiesta con l'Accept intestazione impostata su application/pdf.
Per ottenere i dati della ricevuta si può utilizzare:
GET https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/39f65b28-b1fa-401b-ad58-0addcaef7162
Accept: application/json
Authorization: Bearer <Merchant JWT Token>
Response 200
{
"uuid": "39f65b28-b1fa-401b-ad58-0addcaef7162",
"type": "sale",
"total_amount": "244",
"document_number": "0001-0001",
"document_datetime": "2025-07-22T09:45:22",
"parent_receipt_uuid": null,
"is_voidable": true,
"is_returnable": true,
"html_url": "url/to/html",
"pdf_url": "url/to/pdf"
}
Il PDF invece si può richiedere con:
GET https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/39f65b28-b1fa-401b-ad58-0addcaef7162/details
Accept: application/pdf
Authorization: Bearer <Merchant JWT Token>
Restituzione degli articoli e annullamento della ricevuta tramite API A-Cube
Nella sezione dedicata agli sviluppatori che adottano la nostra API per l’invio dei corrispettivi è possibile come fare per:
restituire gli articoli di una ricevuta di vendita emessa dallo stesso PEM che stai utilizzando;
restituire gli articoli di una ricevuta di vendita emessa da un PEM diverso;
restituire gli articoli di una ricevuta di vendita non emessa da un PEM.
In tutti e tre i casi, è necessario che le ricevute siano state emesse da un commerciante o un cassiere in possesso di un certificato valido (file PEM).
Gli esempi presenti nella guida sono disponibili nei linguaggi Pitone, JavaScript, Bash e PHP.
Tramite l'API A-Cube è possibile anche annullare una ricevuta di vendita. Come per la restituzione degli articoli, nell'apposita sezione della guida sono presenti i riferimenti nei diversi linguaggi. I casi che si verificano - e per i quali sono presenti gli esempi specifichi - sono:
come fare per annullare una ricevuta di vendita emessa dallo stesso PEM da cui si sta operando;
come fare per annullare una ricevuta di vendita emessa da un PEM diverso;
come fare per annullare una ricevuta di vendita non emessa da un PEM.
Invio dei corrispettivi via API: efficienza e controllo con A-Cube
Integrare un’API per l’invio dei corrispettivi nei propri flussi aziendali non significa solo rispettare un obbligo normativo ma costruire un’infrastruttura solida, scalabile e pronta ad evolvere insieme al business. Per farlo, bisogna però individuare la soluzione più idonea. La differenza la fa la capacità di gestire in modo fluido ogni fase del processo, dall’attivazione dei moduli PEM e PEL fino alla gestione di resi e annullamenti. Il tutto senza introdurre complessità superflue. Le API sviluppate da noi di A-Cube sono progettate proprio con questo obiettivo: offrire agli sviluppatori strumenti chiari, documentati e coerenti con le specifiche dell’Agenzia delle Entrate. Vuoi saperne di più? Scrivi a info@acubeapi.com e scopri in che modo le nostre soluzioni API-first possono fare la differenza per il tuo business.
