Il registratore telematico diventa una chiamata API
BillySSW è una Soluzione Software per la memorizzazione elettronica e la trasmissione telematica dei corrispettivi. Il tuo gestionale invia la vendita via REST; Billy genera il documento commerciale e ti restituisce il PDF firmato con il testo per la stampante termica, poi trasmette i corrispettivi all'Agenzia delle Entrate.
- 0 hardware
- Il Punto di Emissione è in cloud: niente RT, niente certificati da installare.
- OAuth 2.0
- Authorization Code + PKCE, consenso esplicito dell'esercente, scope limitati.
- 1 POST
- Una vendita è una chiamata: la risposta è il PDF firmato, con dentro il testo di stampa.
- Staging
- Ambiente di prova completo, senza invii all'Agenzia delle Entrate.
Cos'è una Soluzione Software per i corrispettivi
La nuova normativa introduce la possibilità di emettere i Documenti Commerciali (ex scontrini) con una soluzione interamente software, consentendo quindi di abbandonare il Registratore Telematico. La Soluzione Software BillySSW è certificata ai sensi dell'art. 24, comma 1, del d.lgs. 8 gennaio 2024, n. 1. BillySSW memorizza elettronicamente i dati dei documenti commerciali e li trasmette telematicamente garantendone sicurezza e inalterabilità. Le regole tecniche sono fissate dalle Specifiche Tecniche allegate al Provvedimento del Direttore dell'Agenzia delle Entrate n. 111204 del 7 marzo 2025.
Le Specifiche dividono la soluzione in due moduli fiscali, strettamente interdipendenti:
MF1 · Punto di Emissione (PEM)
Il «registratore»: usato dall'esercente per emettere i documenti commerciali.
- Registra in modo sicuro i dati fiscali di ogni operazione, compresi i pagamenti elettronici
- Emette documenti commerciali di vendita, annullo e reso
- Gestisce i flussi della Lotteria degli scontrini
- Trasmette i dati al Punto di Elaborazione e ne consente la consultazione
MF2 · Punto di Elaborazione (PEL)
Il «server fiscale»: dialoga con il sistema dell'Agenzia delle Entrate.
- Riceve i dati dai PEM collegati
- Predispone e trasmette i file XML giornalieri dei corrispettivi
- Memorizza fiscalmente e conserva digitalmente i dati
- Consente l'interrogazione dei dati ai verificatori
Cosa espongono le API
Dove si colloca il tuo gestionale
Il gestionale resta il punto in cui l'esercente lavora: cassa, catalogo, clienti. Al momento della vendita chiama le API di Billy con il token ottenuto dal consenso dell'esercente. Tutto ciò che è fiscale avviene a valle.
- 1L'esercente autorizza il tuo software e tu ricevi l'access token (OAuth 2.0 con PKCE).
- 2Il gestionale invia la vendita:
POST /api/pem/{serial}/fiscale/invio/dc. - 3Il PEM genera l'XML, lo firma e lo concatena nel Journal.
- 4La risposta arriva subito: il PDF firmato, con progressivo e hash negli header e il testo ESC/POS per la stampante nei metadati.
- 5Il documento viene accodato verso il PEL, senza far attendere la cassa.
- 6Il PEL trasmette i corrispettivi all'Agenzia delle Entrate e ne raccoglie gli esiti, che leggi con le API.
- Tu sei un partner affiliato. Ti candidi una volta sola, indicando già il nome del tuo software e i suoi
redirect_uri; con l'approvazione ricevi il codice partner e ilclient_idOAuth. - L'esercente ha il proprio account Billy, su cui sono registrati i suoi PEM, e autorizza il tuo software dalla schermata di consenso: il gestionale non conosce mai la sua password e non custodisce un client secret.
- Con il token operi sui suoi PEM, e solo su quelli:
GET /api/pemti dice quali sono, con seriale e stato.
Chi fa cosa
Le Specifiche Tecniche definiscono tre ruoli. La software house che si integra via API non assume nessuno di essi: opera per conto dell'esercente, con il suo consenso, sopra una soluzione già certificata.
| Ruolo | Chi | Responsabilità |
|---|---|---|
| Produttore dei moduli fiscali | Sender SRL | Realizza MF1 e MF2 nel rispetto delle Specifiche Tecniche. |
| Erogatore della Soluzione Software | Sender SRL | Rende disponibile la soluzione all'esercente, crea e censisce i PEM, fornisce l'assistenza tecnica. |
| Esercente | Il tuo cliente | Soggetto passivo IVA che effettua le operazioni. Si accredita sul portale Fatture e Corrispettivi e sceglie la tipologia Soluzione Software. |
| Partner integratore | La tua software house | Ruolo commerciale, non fiscale: integra il gestionale con le API e porta i propri esercenti con il codice partner AFF-…. |
Billy Se ne occupa la Soluzione
- Censimento del PEM e certificato presso l'Agenzia
- Generazione, firma e numerazione dei documenti commerciali
- Journal con catena di hash e sua integrità
- Trasmissione dei corrispettivi, esiti, lotteria
- Memorizzazione fiscale e conservazione digitale
- Chiusura automatica entro 24 ore dall'apertura di cassa
Tu Se ne occupa il tuo gestionale
- Interfaccia di cassa e composizione delle righe
- Flusso OAuth e conservazione sicura del refresh token
- Chiamata di emissione con una idempotency_key per documento
- Stampa (ESC/POS) o condivisione del PDF al cliente
Il PEM: un registratore in cloud per ogni cassa
Ogni PEM è un'entità cloud che crea, firma e concatena i documenti per conto dell'esercente. Un esercente può averne più di uno, per esempio una cassa per punto vendita o più casse nello stesso locale.
Seriale
Undici caratteri, per esempio ABCD-0012EF: quattro identificano l'erogatore, un trattino, sei di progressivo. È il serial_number di tutte le chiamate sul PEM.
Creazione
Il primo PEM nasce con l'approvazione dell'esercente, sulla sua sede operativa. I successivi li crea Sender su richiesta: è un'operazione riservata all'Erogatore.
Censimento
Il PEM chiede il certificato all'Agenzia tramite il PEL. Billy verifica l'esito ogni 30 minuti e configura il PEM da sola.
Certificato richiesto all'Agenzia, in attesa dell'esito.
Emette documenti ed esegue la chiusura. Il referente riceve un'email.
Guasto, impossibilità di trasmettere o scelta dell'esercente. Si riattiva via API.
Il PEM è definitivamente cessato.
Il tuo software legge lo stato con GET /api/pem e lo storico con GET …/fiscale/stati; con lo scope fiscale:manage lo cambia con PUT …/fiscale/stato e dismette il PEM con POST …/fiscale/stato/dismissione. Emissione e chiusura richiedono un PEM In servizio. Dettagli in Registrare un PEM.
Una giornata fiscale, dall'apertura alla trasmissione
- AperturaIl primo documento emesso apre la giornata del PEM. Non serve una chiamata dedicata.
- EmissioniOgni vendita, annullo o reso genera un XML firmato che entra nel Journal, concatenato al precedente tramite hash, e viene accodato verso il PEL.
- Chiusura di cassa
POST …/fiscale/invio/chiusuraconsolida il Journal e ne avvia la trasmissione. Risponde subito; il resto avviene in background. Non è necessario effettuare la chiusura manualmente, il sistema la gestisce in automatico entro 24 ore dall'apertura di cassa. - Trasmissione all'AgenziaIl PEL invia i corrispettivi.
GET …/fiscale/richieste?tipo=CORRISPETTIVIelenca gli invii, con stato ed esito XML scaricabile.
Mappa delle API
Tutte le chiamate sul PEM hanno la forma /api/pem/{serial_number}/… e indicano lo scope richiesto. Il riferimento REST descrive ogni campo.
Trasmissionifiscale:manage
- POSTInvio documento commerciale
- POSTAnnullo
- GETRighe rendibili di un DC
- POSTReso
- POSTChiusura giornaliera
Consultazionefiscale:read
- GETRecupero dati di un DC
- POSTReport delle vendite
- GETStorico delle chiusure
PEM e richieste AdEfiscale:read
- GETElenco e dettaglio dei PEM
- GETStorico degli stati
- GETRichieste, stato ed esito XML
Gestione del PEMfiscale:manage
- PUTCambio di stato
- POSTDismissione
- POSTCambio sede
- POSTChiusura di emergenza
Catalogocatalogo:*
- GETReparti e codici ATECO
- POSTCrea reparto o ATECO
- PUTAggiorna
- DELElimina
Documenti gestionali
- GETArchivio e downloadfiscale:read
- POSTOperazioni memorizzatefiscale:manage
- POSTEsiti delle trasmissionifiscale:manage
- POSTChiusura e controllofiscale:manage
Opzioni e segnalazioni
- GETStato e storico buoni pastofiscale:read
- POSTAttiva o disattiva buoni pastofiscale:manage
- GETPeriodi di inattivitàfiscale:read
- POSTSegnala un periodo di inattivitàfiscale:manage
Domande frequenti
Devo certificare il mio gestionale presso l'Agenzia delle Entrate?
No. La Soluzione Software certificata è BillySSW, di cui Sender SRL è produttore ed erogatore. Il tuo gestionale ne usa le API per conto dell'esercente, come farebbe con un registratore telematico collegato.
Serve un registratore telematico o un certificato sul dispositivo?
No. Il PEM è in cloud: il certificato viene ottenuto dal censimento automatico e la firma avviene sui server di Billy. Il dispositivo di cassa deve solo raggiungere le API.
Cosa deve fare l'esercente sul portale Fatture e Corrispettivi?
Accreditarsi e indicare la tipologia Soluzione Software. La creazione e il censimento del PEM li gestisce Billy: l'esercente riceve un'email quando il PEM è In servizio.
Posso creare PEM aggiuntivi dal mio software?
No: la creazione di un PEM è un'operazione dell'Erogatore. L'esercente la chiede a Sender e il nuovo seriale compare in GET /api/pem appena creato.
Cosa succede se la rete cade durante un'emissione?
Ripeti la chiamata con la stessa idempotency_key: se il documento era già stato emesso ricevi quello, altrimenti viene emesso ora. Per questo la chiave va salvata con la vendita prima della chiamata.
Chi trasmette i corrispettivi e chi conserva i dati?
Il PEL di Billy: trasmette i file giornalieri all'Agenzia, ne raccoglie gli esiti e memorizza e conserva digitalmente i dati. Il gestionale può leggere esiti e storico via API.
Quanto dura il collegamento prima di chiedere di nuovo il consenso?
Con lo scope offline_access il refresh token resta valido fino a 30 giorni di inattività e al massimo 90 giorni; poi l'esercente rinnova il consenso.
Da dove partire
Dall'affiliazione al go-live.
OAuth 2.0, scope e durata dei token.
Il primo documento commerciale.
Vendite, annulli, resi e chiusura.
Per domande sull'integrazione scrivi a api@sender.it.