# Panoramica > Cos'è la Soluzione Software, come lavorano PEM e PEL e cosa resta al gestionale che si integra con le API. Pagina HTML: https://app.billyssw.it/documentazione/panoramica Indice della documentazione: https://app.billyssw.it/documentazione/index.md Tutta la documentazione in un file: https://app.billyssw.it/documentazione/full.md ## 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. [Inizia l'integrazione](https://app.billyssw.it/documentazione/checklist)[Il primo documento](https://app.billyssw.it/documentazione/quickstart) 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. Il contesto ### 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 Le API di Billy agiscono sui **PEM** dell'esercente: emissione, consultazione, chiusura, stato. Il PEL non è esposto, perché il dialogo con l'Agenzia delle Entrate è gestito interamente da Billy; il tuo software ne legge solo gli esiti. Architettura ### 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. 1. 1L'esercente autorizza il tuo software e tu ricevi l'access token (OAuth 2.0 con PKCE). 2. 2Il gestionale invia la vendita: `POST /api/pem/{serial}/fiscale/invio/dc`. 3. 3Il PEM genera l'XML, lo firma e lo concatena nel Journal. 4. 4La risposta arriva subito: il PDF firmato, con progressivo e hash negli header e il testo ESC/POS per la stampante nei metadati. 5. 5Il documento viene accodato verso il PEL, senza far attendere la cassa. 6. 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 il `client_id` OAuth. - **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/pem` ti dice quali sono, con seriale e stato. Ruoli ### 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 Punto di Emissione ### 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. In attesa Certificato richiesto all'Agenzia, in attesa dell'esito. In servizio Emette documenti ed esegue la chiusura. Il referente riceve un'email. Fuori servizio Guasto, impossibilità di trasmettere o scelta dell'esercente. Si riattiva via API. Dismissione 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](https://app.billyssw.it/documentazione/nuovopem). Ciclo operativo ### Una giornata fiscale, dall'apertura alla trasmissione 1. **Apertura** Il primo documento emesso apre la giornata del PEM. Non serve una chiamata dedicata. 2. **Emissioni** Ogni vendita, annullo o reso genera un XML firmato che entra nel Journal, concatenato al precedente tramite hash, e viene accodato verso il PEL. 3. **Chiusura di cassa** `POST …/fiscale/invio/chiusura` consolida 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. 4. **Trasmissione all'Agenzia** Il PEL invia i corrispettivi. `GET …/fiscale/richieste?tipo=CORRISPETTIVI` elenca gli invii, con stato ed esito XML scaricabile. Riferimento ### Mappa delle API Tutte le chiamate sul PEM hanno la forma `/api/pem/{serial_number}/…` e indicano lo scope richiesto. Il [riferimento REST](https://app.billyssw.it/documentazione/api) 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 FAQ ### 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. Prossimi passi ### Da dove partire [ Percorso di integrazione Dall'affiliazione al go-live. ](https://app.billyssw.it/documentazione/checklist)[ Autenticazione OAuth 2.0, scope e durata dei token. ](https://app.billyssw.it/documentazione/auth)[ Guida rapida Il primo documento commerciale. ](https://app.billyssw.it/documentazione/quickstart)[ Emettere DC Vendite, annulli, resi e chiusura. ](https://app.billyssw.it/documentazione/receipts) Per domande sull'integrazione scrivi a [api@sender.it](mailto:api@sender.it).