REST API

Tutte le operazioni REST con parametri, corpo della richiesta, risposte ed errori, generate dalla specifica OpenAPI.

Tutte le operazioni pubblicate dell'API fiscale, generate dalla specifica OpenAPI (https://app.billyssw.it/documentazione/openapi.json).

I percorsi sono relativi al base URL dell'ambiente: in staging https://pem-staging.billyssw.it (vedi Base URL, https://app.billyssw.it/documentazione/ambienti). Ogni richiesta porta Accept: application/json.

Autenticazione

Il bearer è un access token del realm Keycloak billy, ottenuto con Authorization Code + PKCE e il consenso dell'esercente. Per i client partner vale 10 minuti: alla scadenza (401 con error: token_expired) se ne chiede uno nuovo al token endpoint del realm con il refresh_token. Ogni endpoint dichiara lo scope richiesto ai client partner; quelli riservati all'app e al pannello Billy rispondono 403 a un client partner.

• Autorizzazione: https://auth.billyssw.it/realms/billy/protocol/openid-connect/auth
• Token e rinnovo: https://auth.billyssw.it/realms/billy/protocol/openid-connect/token

Indice delle operazioni

• Account - Registrazione
  • POST /api/auth/register: Richiesta di registrazione esercente
• Anagrafica - PEM
  • GET /api/pem: Lista PEM
  • GET /api/pem/{serial_number}: Mostra PEM
  • POST /api/pem/{serial_number}/cambio-sede: Richiedi il cambio sede
  • DELETE /api/pem/{serial_number}/cambio-sede/{cambio_sede}: Annulla il cambio sede
• Catalogo - ATECO
  • GET /api/pem/{serial_number}/dati/ateco: Lista ATECO
  • POST /api/pem/{serial_number}/dati/ateco: Crea ATECO
  • PUT /api/pem/{serial_number}/dati/ateco/{id}: Aggiorna ATECO
  • DELETE /api/pem/{serial_number}/dati/ateco/{id}: Elimina ATECO
• Catalogo - Reparti
  • GET /api/pem/{serial_number}/dati/reparti: Lista Reparti
  • POST /api/pem/{serial_number}/dati/reparti: Crea Reparto
  • PUT /api/pem/{serial_number}/dati/reparti/{reparto_id}: Aggiorna Reparto
  • DELETE /api/pem/{serial_number}/dati/reparti/{reparto_id}: Elimina Reparto
• Funzioni fiscali - Consultazione
  • GET /api/pem/{serial_number}/fiscale/chiusure/storico: Storico chiusure
  • GET /api/pem/{serial_number}/fiscale/chiusure/{journalId}/documento: Dati di una chiusura
  • POST /api/pem/{serial_number}/fiscale/consultazione/report: Report
  • GET /api/pem/{serial_number}/fiscale/consultazione/dc: Dettaglio di un DC
  • GET /pem/{serial_number}/fiscale/consultazione/dc/{hash}/pdf: PDF pubblico di un DC
• Funzioni fiscali - Controllo PEM
  • GET /api/pem/{serial_number}/controllo: Dati di controllo AdE del PEM
  • POST /api/pem/{serial_number}/fiscale/gestionali/controllo: Emetti Documento Gestionale di Controllo
• Funzioni fiscali - Documenti gestionali
  • GET /api/pem/{serial_number}/fiscale/gestionali: Archivio documenti gestionali
  • GET /api/pem/{serial_number}/fiscale/gestionali/{id}/pdf: Download di un documento gestionale archiviato
  • POST /api/pem/{serial_number}/fiscale/gestionali/operazioni: Documento gestionale operazioni memorizzate
  • POST /api/pem/{serial_number}/fiscale/gestionali/esiti-trasmissione: Documento gestionale esiti trasmissioni corrispettivi
  • POST /api/pem/{serial_number}/fiscale/gestionali/storico-buoni-pasto: Documento gestionale storico opzione buoni pasto
  • POST /api/pem/{serial_number}/fiscale/gestionali/chiusura/{journalId}: Documento gestionale di chiusura
• Funzioni fiscali - Emergenza
  • POST /api/pem/{serial_number}/fiscale/emergenza/chiusura: Chiusura di emergenza
• Funzioni fiscali - Opzione buoni pasto
  • GET /api/pem/{serial_number}/fiscale/opzione-buoni-pasto: Stato opzione buoni pasto
  • POST /api/pem/{serial_number}/fiscale/opzione-buoni-pasto: Attiva/disattiva opzione buoni pasto
  • GET /api/pem/{serial_number}/fiscale/opzione-buoni-pasto/storico: Storico opzione buoni pasto
• Funzioni fiscali - Richieste PEM
  • GET /api/pem/{serial_number}/fiscale/richieste: Lista richieste
  • GET /api/pem/{serial_number}/fiscale/richieste/stato/{idRichiesta}: Verifica stato richiesta
  • GET /api/pem/{serial_number}/fiscale/richieste/esito/{idRichiesta}: Recupera esito richiesta
• Funzioni fiscali - Segnalazioni
  • GET /api/pem/{serial_number}/fiscale/segnalazioni/inattivita: Periodi di inattività
  • POST /api/pem/{serial_number}/fiscale/segnalazioni/inattivita: Segnala un periodo di inattività
• Funzioni fiscali - Stato PEM
  • GET /api/pem/{serial_number}/fiscale/stati: Lista Stati PEM
  • PUT /api/pem/{serial_number}/fiscale/stato: Modifica lo stato del PEM
  • POST /api/pem/{serial_number}/fiscale/stato/dismissione: Dismissione del PEM
• Funzioni fiscali - Trasmissioni
  • POST /api/pem/{serial_number}/fiscale/invio/dc: Invio DC
  • POST /api/pem/{serial_number}/fiscale/invio/annullo: Annulla DC
  • GET /api/pem/{serial_number}/fiscale/invio/reso: Recupera dati reso DC
  • POST /api/pem/{serial_number}/fiscale/invio/reso: Reso DC
  • POST /api/pem/{serial_number}/fiscale/invio/chiusura: Chiusura giornaliera

Account - Registrazione

Richiesta di registrazione esercente

POST /api/auth/register

Pubblica: nessun token.

Registra la richiesta di adesione di un esercente, senza credenziali: la esamina l'erogatore e, all'approvazione, l'esercente riceve l'email per scegliere la password. affiliate_code è il codice del partner che l'ha portato (AFF-…), facoltativo.

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "nome": "Mario",
    "cognome": "Rossi",
    "email": "mario.rossi@example.it",
    "telefono": "3331234567",
    "partita_iva": "01234567897",
    "codice_fiscale": "RSSMRA80A01F205X",
    "denominazione": "Bar Centrale di Mario Rossi",
    "indirizzo": "Via Roma",
    "civico": "1",
    "cap": "20121",
    "comune": "Milano",
    "provincia": "MI",
    "nazione": "IT",
    "regime_fiscale": "ordinario",
    "privacy": true
}

Risposte

• 200 — Richiesta registrata

{
    "success": true,
    "message": "Registrazione avvenuta con successo"
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

• 429 — Troppe richieste

{
    "success": false,
    "message": "Troppe richieste di registrazione: riprova tra qualche minuto",
    "error": "too_many_requests"
}

Anagrafica - PEM

Lista PEM

GET /api/pem

Scope richiesto ai client partner: fiscale:read.

Mostra la lista dei PEM associati all'utente autenticato.

Risposte

• 200 — success

{
    "success": true,
    "pem": [
        {
            "id": 1,
            "serial_number": "ASVS-241232",
            "stato": "In servizio",
            "created_at": "01-01-2025 13:00:00",
            "indirizzo": "Via Roma 1"
        }
    ]
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

Mostra PEM

GET /api/pem/{serial_number}

Scope richiesto ai client partner: fiscale:read.

Mostra i dettagli del PEM indicato.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "pem": {
        "id": 1,
        "serial_number": "ASVS-241232",
        "stato": "In servizio",
        "created_at": "01-01-2025 13:00:00",
        "indirizzo": "Via Roma 1"
    }
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Richiedi il cambio sede

POST /api/pem/{serial_number}/cambio-sede

Scope richiesto ai client partner: fiscale:manage.

Chiede di spostare il PEM a un nuovo indirizzo. Se serve l'approvazione dell'erogatore la richiesta resta in attesa; una volta approvata l'emissione è sospesa fino alla chiusura di giornata e la nuova sede vale dalla prima emissione successiva.

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "indirizzo": "Via Garibaldi",
    "civico": "12",
    "cap": "20121",
    "comune": "Milano",
    "provincia": "MI",
    "nazione": "IT",
    "sede_legale": false
}

Risposte

• 200 — Richiesta registrata

{
    "success": true,
    "cambio_sede": {
        "id": 3,
        "stato": "richiesta",
        "indirizzo": "Via Garibaldi",
        "civico": "12",
        "cap": "20121",
        "comune": "Milano",
        "provincia": "MI",
        "nazione": "IT",
        "sede_legale": false,
        "motivazione_rifiuto": null,
        "created_at": "08-10-2026 10:15:42",
        "approvato_il": null
    },
    "message": "Richiesta inviata: dopo l'approvazione dell'erogatore l'emissione sarà sospesa fino alla chiusura di giornata, poi la nuova sede sarà applicata automaticamente alla prima emissione"
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

Annulla il cambio sede

DELETE /api/pem/{serial_number}/cambio-sede/{cambio_sede}

Scope richiesto ai client partner: fiscale:manage.

Ritira una richiesta di cambio sede non ancora applicata (409 se non è più annullabile).

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "message": "Richiesta di cambio sede annullata"
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Catalogo - ATECO

Lista ATECO

GET /api/pem/{serial_number}/dati/ateco

Scope richiesto ai client partner: catalogo:read.

Restituisce i codici ATECO associati al PEM indicato.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "ateco": [
        {
            "id": 1,
            "codice": "112233",
            "descrizione": "TEST ATECO"
        }
    ]
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Crea ATECO

POST /api/pem/{serial_number}/dati/ateco

Scope richiesto ai client partner: catalogo:write.

Crea un nuovo codice ATECO associato al PEM indicato.

Parametri di percorso

Corpo della richiesta (application/json)

Esempio:

{
    "ateco": {
        "descrizione": "Commercio al dettaglio",
        "codice": "47.11.00"
    }
}

Risposte

• 200 — success

{
    "success": true,
    "message": "ATECO creato con successo",
    "ateco": {
        "id": 1,
        "codice": "112233",
        "descrizione": "TEST ATECO"
    }
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Validazione fallita

{
    "success": false,
    "message": "Il campo codice è obbligatorio",
    "errors": {
        "ateco.codice": [
            "Il campo codice è obbligatorio"
        ]
    }
}

Aggiorna ATECO

PUT /api/pem/{serial_number}/dati/ateco/{id}

Scope richiesto ai client partner: catalogo:write.

Aggiorna un codice ATECO esistente associato al PEM indicato.

Parametri di percorso

Corpo della richiesta (application/json)

Esempio:

{
    "ateco": {
        "descrizione": "Commercio al dettaglio",
        "codice": "47.11.00"
    }
}

Risposte

• 200 — success

{
    "success": true,
    "message": "ATECO aggiornato con successo",
    "ateco": {
        "id": 1,
        "codice": "112233",
        "descrizione": "TEST ATECO"
    }
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — ATECO non trovato

{
    "success": false,
    "message": "La risorsa richiesta non è stata trovata."
}

• 422 — Validazione fallita

{
    "success": false,
    "message": "Il campo codice è obbligatorio",
    "errors": {
        "ateco.codice": [
            "Il campo codice è obbligatorio"
        ]
    }
}

Elimina ATECO

DELETE /api/pem/{serial_number}/dati/ateco/{id}

Scope richiesto ai client partner: catalogo:write.

Elimina un codice ATECO associato al PEM indicato.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "message": "ATECO eliminato con successo"
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — ATECO non trovato

{
    "success": false,
    "message": "La risorsa richiesta non è stata trovata."
}

Catalogo - Reparti

Lista Reparti

GET /api/pem/{serial_number}/dati/reparti

Scope richiesto ai client partner: catalogo:read.

Mostra la lista dei reparti associati al PEM corrente.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "reparti": [
        {
            "id": 1,
            "sigla": "R1",
            "descrizione": "Reparto 1",
            "importo": 100,
            "iva": "22",
            "colore": "#FFFFFF",
            "bene_servizio": "B",
            "id_categoria": 1,
            "id_ateco": 1
        }
    ]
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Crea Reparto

POST /api/pem/{serial_number}/dati/reparti

Scope richiesto ai client partner: catalogo:write.

Memorizza un nuovo reparto associato al PEM corrente.

Parametri di percorso

Corpo della richiesta (application/json)

Esempio:

{
    "reparto": {
        "sigla": "A",
        "descrizione": "Caffetteria",
        "importo": 1.2,
        "iva": "10",
        "bene_servizio": "B"
    }
}

Risposte

• 200 — success

{
    "success": true,
    "message": "Reparto creato con successo",
    "reparto": {
        "id": 1,
        "sigla": "R1",
        "descrizione": "Reparto 1",
        "importo": 100,
        "iva": "22",
        "colore": "#FFFFFF",
        "bene_servizio": "B",
        "id_categoria": 1,
        "id_ateco": 1
    }
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Validazione fallita

{
    "success": false,
    "message": "Il campo iva è obbligatorio",
    "errors": {
        "reparto.iva": [
            "Il campo iva è obbligatorio"
        ]
    }
}

Aggiorna Reparto

PUT /api/pem/{serial_number}/dati/reparti/{reparto_id}

Scope richiesto ai client partner: catalogo:write.

Aggiorna un reparto esistente associato al PEM indicato.

Parametri di percorso

Corpo della richiesta (application/json)

Esempio:

{
    "reparto": {
        "sigla": "A",
        "descrizione": "Caffetteria",
        "importo": 1.2,
        "iva": "10",
        "bene_servizio": "B"
    }
}

Risposte

• 200 — success

{
    "success": true,
    "message": "Reparto aggiornato con successo",
    "reparto": {
        "id": 1,
        "sigla": "R1",
        "descrizione": "Reparto 1",
        "importo": 100,
        "iva": "22",
        "colore": "#FFFFFF",
        "bene_servizio": "B",
        "id_categoria": 1,
        "id_ateco": 1
    }
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Reparto non trovato

{
    "success": false,
    "message": "La risorsa richiesta non è stata trovata."
}

• 422 — Validazione fallita

{
    "success": false,
    "message": "Aliquota non valida",
    "errors": {
        "reparto.iva": [
            "Aliquota non valida"
        ]
    }
}

Elimina Reparto

DELETE /api/pem/{serial_number}/dati/reparti/{reparto_id}

Scope richiesto ai client partner: catalogo:write.

Elimina un reparto associato al PEM indicato.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "message": "Reparto eliminato con successo"
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Reparto non trovato

{
    "success": false,
    "message": "La risorsa richiesta non è stata trovata."
}

Funzioni fiscali - Consultazione

Storico chiusure

GET /api/pem/{serial_number}/fiscale/chiusure/storico

Scope richiesto ai client partner: fiscale:read.

Elenca le giornate chiuse del PEM, dalla più recente, con il numero di DC e la data di trasmissione al PEL (inviato_il nullo = chiusura non ancora trasmessa). journal_aperto è la giornata in corso, nullo se la cassa è chiusa. data_chiusura è in ora locale; inviato_il e aperto_il in UTC.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "chiusure": [
        {
            "id": 12,
            "progressivo": 12,
            "data_chiusura": "2026-10-07T21:30:00",
            "numero_dc": 48,
            "numero_dc_journal": 48,
            "inviato_il": "2026-10-07T19:30:04.000000Z"
        }
    ],
    "journal_aperto": {
        "id": 13,
        "progressivo": 13,
        "aperto_il": "2026-10-08T06:02:11.000000Z"
    }
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Dati di una chiusura

GET /api/pem/{serial_number}/fiscale/chiusure/{journalId}/documento

Scope richiesto ai client partner: fiscale:read.

Restituisce i dati della giornata fiscale chiusa (journalId da Storico chiusure): dati locali della chiusura uniti ai totali del PEL, unica fonte fiscale. Finché la chiusura non è stata trasmessa all'AdE il PEL non ha i totali e la risposta è 409.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "documento": {
        "pem": {
            "serial_number": "ASVS-241232",
            "indirizzo": "Via Roma 1",
            "comune": "Milano",
            "cap": "20100",
            "provincia": "MI"
        },
        "esercente": {
            "denominazione": "Bar Centrale srl",
            "partita_iva": "01234567890"
        },
        "journal": {
            "progressivo": 12,
            "data_chiusura": "2026-10-07T21:30:00",
            "numero_dc": 48,
            "numero_dc_journal": 48
        },
        "riepilogo": [],
        "pagamenti": [],
        "riepiloghi": [],
        "chiusure": [],
        "buoni_pasto": {
            "attiva": false,
            "aggiornato_il": null
        }
    }
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 — Corrispettivi non trasmessi

{
    "success": false,
    "message": "Chiusura non ancora trasmessa all'AdE"
}

Report

POST /api/pem/{serial_number}/fiscale/consultazione/report

Scope richiesto ai client partner: fiscale:read.

Elabora il report delle vendite del PEM indicato

Parametri di percorso

Corpo della richiesta (application/json)

Esempio:

{
    "data_inizio": "2026-10-01",
    "data_fine": "2026-10-31"
}

Risposte

• 200 — success

{
    "success": true,
    "scontrini": [
        {
            "id": 102,
            "user": "EsercenteTEST",
            "tipo": "DC",
            "progressivo": "0089-0001",
            "data": "2025-07-22 14:58:57",
            "inviato_il": "2025-07-22 14:59:02",
            "importo": 377.5,
            "pagamenti_metodo": "PC",
            "progressivo_riferimento": null,
            "annullato": false,
            "reso_fatto": false,
            "hash": "NmNhMzI5MDc3NjY2YzI5OTk2NDBiODg5YmFhMjEyMDI3MzZlZmNiNTMzMjEzNDQxNDE1YzQ1MmZlYWMyMjYyZTlmMTljMWVkYzFmN2UzMGU2ODYxMGIxMzVjZmJiMDBjNDAwMDI5NmQ5YTk1ODk4ZDI4NWQ3NmU1MjI5ZTkwMzg="
        }
    ],
    "totali": {
        "totaleLordo": 377.5,
        "totaleAnnulli": 0,
        "totaleResi": 0,
        "pagamenti": {
            "contanti": 377,
            "elettronico": 0,
            "ticket": 0,
            "nonRiscossoBeni": 0,
            "nonRiscossoServizi": 0,
            "nonRiscossoFattura": 0,
            "scontoAPagare": 0
        },
        "iva": {
            "10": {
                "imponibile": 70.45454545,
                "importo": 7.04545455
            },
            "N2": {
                "imponibile": 100,
                "importo": 0
            },
            "N4": {
                "imponibile": 200,
                "importo": 0
            }
        },
        "reparto": {
            "Nessuno": 377.5
        },
        "totaleOmaggi": 0
    }
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

Dettaglio di un DC

GET /api/pem/{serial_number}/fiscale/consultazione/dc

Scope richiesto ai client partner: fiscale:read.

Restituisce un documento commerciale del PEM nello stesso formato della risposta di emissione: con id quello indicato, senza l'ultimo emesso dall'utente del token.

Parametri di percorso

Parametri della query

Risposte

• 200 — Il documento commerciale (abbreviato)

{
    "success": true,
    "dati": {
        "tipo": "DC",
        "progressivo": "0012-0007",
        "data": "2026-10-08 10:15:42",
        "hash": "YjQ0ZDJmMGE5YzFl...MmEzYjQ=",
        "codice_lotteria": null,
        "cessionario_committente": null,
        "elementi_contabili": [
            {
                "id": 5531,
                "descrizione": "Caffè espresso",
                "bene_servizio": "B",
                "quantita": "2.00",
                "prezzo_unitario": "1.20",
                "sconto": "0.00",
                "iva": "10",
                "acconto_versato_beni_non_consegnati": false,
                "omaggio": false
            }
        ],
        "pagamenti_dc": [
            {
                "importo": "2.40",
                "metodo": "PC"
            }
        ],
        "condivisione": {
            "testo_stampa": "G0AbYQFCQVIgQ0VOVFJBTEUg...",
            "pdf_url": "https://pem-staging.billyssw.it/pem/ASVS-241232/fiscale/consultazione/dc/YjQ0ZDJmMGE5YzFl...MmEzYjQ%3D/pdf"
        }
    }
}

• 401 —

{
    "success": false,
    "message": "Il token di accesso non è valido.",
    "error": "token_invalid"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Documento inesistente

{
    "success": false,
    "errore": "Documento commerciale non trovato"
}

PDF pubblico di un DC

GET /pem/{serial_number}/fiscale/consultazione/dc/{hash}/pdf

Pubblica: nessun token.

Il PDF firmato del documento, senza token: è l'URL di Content-Location della risposta di emissione. Sta fuori da /api. Limite di 60 richieste al minuto per indirizzo IP. width e font_size cambiano solo il PDF: il testo ESC/POS nei metadati segue le impostazioni di stampa dell'esercente.

Parametri di percorso

Parametri della query

Risposte

• 200 — Il PDF firmato del documento.

Corpo: application/pdf, binario.

• 429 — Più di 60 richieste al minuto dallo stesso indirizzo IP.

{
    "message": "Too Many Attempts."
}

Funzioni fiscali - Controllo PEM

Dati di controllo AdE del PEM

GET /api/pem/{serial_number}/controllo

Scope richiesto ai client partner: fiscale:read.

Restituisce i dati identificativi, di stato e di versione richiesti per il controllo del PEM.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "data": {
        "matricola": "ASVS-000001",
        "stato": "In servizio",
        "data_cambio_stato": "01-01-2025 10:00:00",
        "esercente": {
            "partita_iva": "12345678901",
            "codice_fiscale": "RSSMRA80A01H501Z",
            "denominazione": "Esercente Srl"
        },
        "erogatore": {
            "partita_iva": "12345678901",
            "codice_fiscale": "RSSMRA80A01H501Z",
            "denominazione": "Erogatore Srl"
        },
        "soluzione_software": {
            "sigla": "123e4567-e89b-12d3-a456-426614174000",
            "id_approvazione": "0000",
            "data_approvazione": null
        },
        "versione_installata": {
            "versione": 1,
            "sotto_versione": 0,
            "patch": "0",
            "data_ora": "01-01-2025 10:00:00",
            "swid": null
        },
        "versione_disponibile": {
            "versione": 1,
            "sotto_versione": 0,
            "patch": "0",
            "data_creazione": "01-01-2025 10:00:00",
            "data_approvazione": null,
            "swid": null
        },
        "dc_non_trasmessi": {
            "count": 3,
            "importo_totale": 125.5
        }
    }
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa."
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — PEM non trovato

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Emetti Documento Gestionale di Controllo

POST /api/pem/{serial_number}/fiscale/gestionali/controllo

Scope richiesto ai client partner: fiscale:manage.

Genera il PDF dei dati di controllo del PEM lato backend e lo archivia come Documento Gestionale (tipo controllo), restituendolo in download.

Parametri di percorso

Risposte

• 200 — Il PDF firmato del documento gestionale.

Corpo: application/pdf, binario.

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa."
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — PEM non trovato

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 — Nessun Journal aperto

{
    "success": false,
    "message": "Nessun Journal aperto disponibile"
}

Funzioni fiscali - Documenti gestionali

Archivio documenti gestionali

GET /api/pem/{serial_number}/fiscale/gestionali

Scope richiesto ai client partner: fiscale:read.

Elenca i documenti gestionali del PEM, di qualunque tipo, filtrabili per data di elaborazione e per tipo. Senza Accept: application/json rende la pagina Inertia dell'archivio.

Parametri di percorso

Parametri della query

Risposte

• 200 — I documenti gestionali del PEM, dal più recente

{
    "success": true,
    "gestionali": [
        {
            "id": 5,
            "progressivo": "0012-0001",
            "tipo": "operazioni",
            "data_elaborazione": "2026-10-08T10:15:42+02:00",
            "parametri": {
                "selezione": "date",
                "data_inizio": "2026-10-01",
                "data_fine": "2026-10-08"
            }
        }
    ]
}

• 401 —

{
    "success": false,
    "message": "Il token di accesso non è valido.",
    "error": "token_invalid"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Download di un documento gestionale archiviato

GET /api/pem/{serial_number}/fiscale/gestionali/{id}/pdf

Scope richiesto ai client partner: fiscale:read.

Restituisce il PDF firmato già emesso, qualunque ne sia il tipo.

Parametri di percorso

Risposte

• 200 — Il PDF firmato del documento gestionale.

Corpo: application/pdf, binario.

• 401 —

{
    "success": false,
    "message": "Il token di accesso non è valido.",
    "error": "token_invalid"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Non trovato

{
    "success": false,
    "message": "Documento gestionale non trovato"
}

Documento gestionale operazioni memorizzate

POST /api/pem/{serial_number}/fiscale/gestionali/operazioni

Scope richiesto ai client partner: fiscale:manage.

Emette e restituisce il documento gestionale con le operazioni memorizzate dal PEM secondo la chiave di selezione indicata (ST v1.4 §3.4.2, punti 1-4). La selezione integrale produce il solo riepilogo; le selezioni delimitate includono anche il dettaglio per documento e gli aggregati giornalieri.

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "selezione": "date",
    "data_inizio": "2026-10-01",
    "data_fine": "2026-10-08"
}

Risposte

• 200 — Il PDF firmato del documento gestionale.

Corpo: application/pdf, binario.

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 — Cassa chiusa

{
    "success": false,
    "message": "Nessun Journal aperto disponibile"
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

Documento gestionale esiti trasmissioni corrispettivi

POST /api/pem/{serial_number}/fiscale/gestionali/esiti-trasmissione

Scope richiesto ai client partner: fiscale:manage.

Emette e restituisce il documento gestionale con gli esiti delle trasmissioni dei corrispettivi comprese tra due date (ST v1.4 §3.4.2, punto 5). I dati provengono da richieste_pem: nessuna chiamata al PEL.

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "data_inizio": "2026-01-01",
    "data_fine": "2026-08-20"
}

Risposte

• 200 — Il PDF firmato del documento gestionale.

Corpo: application/pdf, binario.

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 — Cassa chiusa

{
    "success": false,
    "message": "Nessun Journal aperto disponibile"
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

Documento gestionale storico opzione buoni pasto

POST /api/pem/{serial_number}/fiscale/gestionali/storico-buoni-pasto

Scope richiesto ai client partner: fiscale:manage.

Emette e restituisce il documento gestionale con lo storico delle attivazioni e disattivazioni dell'opzione buoni pasto (ST v1.4 §3.4.2, punto 8). Nessun parametro di selezione.

Parametri di percorso

Risposte

• 200 — Il PDF firmato del documento gestionale.

Corpo: application/pdf, binario.

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 — Cassa chiusa

{
    "success": false,
    "message": "Nessun Journal aperto disponibile"
}

Documento gestionale di chiusura

POST /api/pem/{serial_number}/fiscale/gestionali/chiusura/{journalId}

Scope richiesto ai client partner: fiscale:manage.

Emette il Documento Gestionale PDF firmato della giornata fiscale chiusa. I totali provengono dal PEL, unica fonte fiscale. Come per il report vendite ogni richiesta emette un nuovo documento, numerato sul journal corrente; le copie già emesse restano scaricabili dall'archivio gestionali.

Parametri di percorso

Risposte

• 200 — Il PDF firmato del documento gestionale.

Corpo: application/pdf, binario.

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 — Corrispettivi non trasmessi

{
    "success": false,
    "message": "Chiusura non ancora trasmessa all'AdE"
}

Funzioni fiscali - Emergenza

Chiusura di emergenza

POST /api/pem/{serial_number}/fiscale/emergenza/chiusura

Scope richiesto ai client partner: fiscale:manage.

Trasmette al PEL gli aggregati della giornata annotati sul registro di emergenza dei corrispettivi: riepiloghi IVA e totali dei pagamenti, dichiarati dall'esercente. Ammessa solo a PEM Fuori servizio; la chiusura riguarda la giornata in cui è inviata.

Una giornata ammette più chiusure, anche con dati diversi: ogni idempotency_key (UUID scelto dal client) è una chiusura e un invio distinto al PEL. Ripetere la chiamata con la stessa chiave è sicuro: se la chiusura è già trasmessa si riceve il suo esito senza un nuovo invio, se l'invio era fallito lo si ritenta. La stessa chiave con dati diversi, o già usata su un altro PEM, è rifiutata (422).

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "idempotency_key": "3f1c2a9e-8b7d-4c1e-9a2f-5d6e7f8a9b0c",
    "n_doc_commerciali": 12,
    "riepiloghi": [
        {
            "iva": "22",
            "importo_parziale": "100.00",
            "imposta": "22.00"
        },
        {
            "iva": "10",
            "importo_parziale": "50.50",
            "imposta": "5.05"
        }
    ],
    "totali": {
        "pagato_contanti": "100.00",
        "pagato_elettronico": "77.55",
        "sconto_a_pagare": "0.00"
    }
}

Risposte

• 200 — success

{
    "success": true,
    "dati": {
        "id_presa_in_carico": "12345",
        "n_doc_commerciali": 12
    }
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 —

Funzioni fiscali - Opzione buoni pasto

Stato opzione buoni pasto

GET /api/pem/{serial_number}/fiscale/opzione-buoni-pasto

Scope richiesto ai client partner: fiscale:read.

Restituisce lo stato efficace dell'opzione (quello che governa l'emissione) e, se una scelta è stata registrata ma decorre dal primo giorno del mese successivo (§5.3), anche la scelta in sospeso.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "attiva": true,
    "opzione": {
        "attiva": true,
        "aggiornato_il": "12-08-2026 10:00:00",
        "decorre_dal": "12-08-2026 10:00:00"
    },
    "scelta_pendente": null,
    "modificabile": true
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Attiva/disattiva opzione buoni pasto

POST /api/pem/{serial_number}/fiscale/opzione-buoni-pasto

Scope richiesto ai client partner: fiscale:manage.

Registra l'attivazione o disattivazione dell'opzione per il trattamento dei buoni pasto (ST v1.4 §5.3). Ammessa solo a cassa chiusa. Ha effetto dal momento della scelta, salvo che nel mese corrente sia già stato emesso almeno un DC con buoni pasto accettati: in tal caso decorre dal primo giorno del mese successivo (campo decorre_dal della risposta).

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "attiva": true
}

Risposte

• 200 — success

{
    "success": true,
    "message": "Opzione buoni pasto aggiornata",
    "opzione": {
        "attiva": true,
        "aggiornato_il": "12-08-2026 10:00:00",
        "decorre_dal": "01-09-2026 00:00:00"
    }
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Ruolo non ammesso

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Cassa aperta

{
    "error_code": "BP001",
    "message": "Impossibile modificare opzione buoni pasto. Effettua chiusura di cassa e riprova."
}

Storico opzione buoni pasto

GET /api/pem/{serial_number}/fiscale/opzione-buoni-pasto/storico

Scope richiesto ai client partner: fiscale:read.

Restituisce lo storico delle attivazioni/disattivazioni dell'opzione, come richiesto dalle ST v1.4 (§3.4.2, lettura e stampa).

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "storico": [
        {
            "attiva": true,
            "aggiornato_il": "12-08-2026 10:00:00",
            "utente": "Mario Rossi"
        }
    ]
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Funzioni fiscali - Richieste PEM

Lista richieste

GET /api/pem/{serial_number}/fiscale/richieste

Scope richiesto ai client partner: fiscale:read.

Recupera la lista delle richieste effettuate dal PEM specificato.

Parametri di percorso

Parametri della query

Risposte

• 200 — success

{
    "success": true,
    "message": "Richieste PEM recuperate",
    "richieste": [
        {
            "id": 1,
            "id_presa_in_carico": "ABC123",
            "stato": "PRONTA",
            "data": "2025-07-01 10:30:00",
            "tipo": "CENSIMENTO"
        }
    ]
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

Verifica stato richiesta

GET /api/pem/{serial_number}/fiscale/richieste/stato/{idRichiesta}

Scope richiesto ai client partner: fiscale:read.

Controlla lo stato attuale di una richiesta PEM specifica.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "message": "Stato richiesta: COMPLETED",
    "stato": "COMPLETED"
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Recupera esito richiesta

GET /api/pem/{serial_number}/fiscale/richieste/esito/{idRichiesta}

Scope richiesto ai client partner: fiscale:read.

Recupera l'esito finale di una richiesta pronta. Se l'esito è già presente nel database, lo restituisce direttamente senza effettuare una nuova chiamata al PEL.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "message": "Esito richiesta recuperato",
    "esito": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Funzioni fiscali - Segnalazioni

Periodi di inattività

GET /api/pem/{serial_number}/fiscale/segnalazioni/inattivita

Scope richiesto ai client partner: fiscale:read.

Elenca i periodi di inattività segnalati per il PEM, dal più recente, con lo stato dell'inoltro al PEL.

Parametri di percorso

Risposte

• 200 — success

{
    "status": "success",
    "data": [
        {
            "id": 3,
            "serial_number": "ASVS-241232",
            "dal": "2026-12-24 00:00:00",
            "al": "2027-01-06 23:59:59",
            "stato": "PENDING"
        }
    ]
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Segnala un periodo di inattività

POST /api/pem/{serial_number}/fiscale/segnalazioni/inattivita

Scope richiesto ai client partner: fiscale:manage.

Comunica all'AdE, tramite il PEL, un periodo futuro in cui il PEM non emetterà documenti (ferie, chiusura stagionale). La segnalazione è accodata e inoltrata in modo asincrono: la risposta è 202. Le date sono nel formato Y-m-d H:i:s, al successiva a dal e nel futuro.

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "dal": "2026-11-01 00:00:00",
    "al": "2026-11-30 23:59:59"
}

Risposte

• 202 — success

{
    "status": "success",
    "message": "Periodo inattivo registrato"
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

Funzioni fiscali - Stato PEM

Lista Stati PEM

GET /api/pem/{serial_number}/fiscale/stati

Scope richiesto ai client partner: fiscale:read.

Restituisce la lista degli stati del PEM corrente.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "data": [
        {
            "id": 1,
            "stato": "In servizio"
        },
        {
            "id": 2,
            "stato": "Dismesso"
        }
    ]
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

Modifica lo stato del PEM

PUT /api/pem/{serial_number}/fiscale/stato

Scope richiesto ai client partner: fiscale:manage.

Comunica al PEL il cambio di stato del PEM.

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "stato": "01",
    "motivazione": "01",
    "note": "Guasto alla rete del punto vendita"
}

Risposte

• 200 — success

{
    "success": true,
    "message": "Stato PEM aggiornato con successo",
    "data": {
        "id": 1,
        "stato": "In servizio"
    }
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Validazione fallita

{
    "success": false,
    "message": "La motivazione è obbligatoria",
    "errors": {
        "motivazione": [
            "Il campo motivazione è obbligatorio"
        ]
    }
}

Dismissione del PEM

POST /api/pem/{serial_number}/fiscale/stato/dismissione

Scope richiesto ai client partner: fiscale:manage.

Porta il PEM nello stato definitivo Dismesso e lo comunica al PEL. Riservata all'esercente titolare; lo stato e la motivazione non si scelgono (campi rifiutati).

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "note": "Chiusura definitiva del ciclo di vita PEM"
}

Risposte

• 200 — success

{
    "success": true,
    "message": "Dismissione PEM completata con successo",
    "data": {
        "id": 7,
        "stato": "Dismesso"
    }
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

Funzioni fiscali - Trasmissioni

Invio DC

POST /api/pem/{serial_number}/fiscale/invio/dc

Scope richiesto ai client partner: fiscale:manage.

Emette un documento commerciale di vendita: genera e firma l'XML, lo aggiunge al Journal e ne accoda la trasmissione al PEL (la risposta non attende il PEL). Ammesso solo su un PEM In servizio.

idempotency_key (UUID) rende sicuro ripetere la chiamata: con una chiave già usata sul PEM la risposta è il documento già emesso, senza emetterne un altro. Come richiesto dalle specifiche AdE, l'unico output è lo stream di byte del PDF firmato (PAdES, application/pdf): il testo ESC/POS per la stampante termica è nei metadati XMP del PDF (billy:escPosBase64) e Content-Location è l'URL pubblico dello stesso PDF (con ?regalo=1 la copia di cortesia). Gli errori restano JSON. Il primo DC dopo una chiusura apre la nuova giornata.

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "idempotency_key": "3f1c2a9e-8b7d-4c1e-9a2f-5d6e7f8a9b0c",
    "elementi": [
        {
            "descrizione": "Caffè espresso",
            "bene_servizio": "B",
            "quantita": "2",
            "prezzo_unitario": "1.20",
            "iva": "10"
        }
    ],
    "pagamenti": [
        {
            "metodo": "PC",
            "importo": "2.40"
        }
    ]
}

Risposte

• 200 — Il PDF firmato (PAdES) del documento emesso.

Corpo: application/pdf, binario.

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 — Giornata aperta da più di 24 ore

{
    "error_code": "JN002",
    "message": "Apertura effettuata da più di 24 ore (ID: 42, Data: 2026-10-07 08:00:00)"
}

• 422 — Validazione fallita

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

• 502 — Il PEL non ha aperto la nuova giornata (JN004): il documento non è emesso, ripetere con la stessa idempotency_key.

{
    "error_code": "JN004",
    "message": "Errore apertura journal PEL: …"
}

Annulla DC

POST /api/pem/{serial_number}/fiscale/invio/annullo

Scope richiesto ai client partner: fiscale:manage.

Emette il documento commerciale di annullo di una vendita e ne accoda la trasmissione al PEL. Per una vendita dello stesso PEM basta il suo progressivo (NNNN-PPPP): righe e codice lotteria si prendono dall'originale. Per un documento di un altro dispositivo si indicano matricola_annullo, progressivo, dataOra ed elementi; con matricola POS, VR o ND il progressivo non serve. La risposta, come per Invio DC, è il PDF firmato del documento.

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "idempotency_key": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "progressivo": "0012-0007"
}

Risposte

• 200 — Il PDF firmato (PAdES) del documento emesso.

Corpo: application/pdf, binario.

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Documento inesistente

{
    "error_code": "DC001",
    "message": "Documento commerciale non trovato"
}

• 409 — Già annullato

{
    "error_code": "DC003",
    "message": "Il documento commerciale è già stato annullato"
}

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

• 502 — Il PEL non ha aperto la nuova giornata (JN004): il documento non è emesso, ripetere con la stessa idempotency_key.

{
    "error_code": "JN004",
    "message": "Errore apertura journal PEL: …"
}

Recupera dati reso DC

GET /api/pem/{serial_number}/fiscale/invio/reso

Scope richiesto ai client partner: fiscale:manage.

Restituisce le righe di un documento commerciale, con il loro id e la quantità già resa (reso), per comporre la richiesta di reso.

Parametri di percorso

Parametri della query

Risposte

• 200 — success

{
    "success": true,
    "dati": {
        "progressivo": "0012-0007",
        "data": "2026-10-08 10:15:42",
        "serial_number": "ASVS-241232",
        "elementi_contabili": [
            {
                "id": 5531,
                "descrizione": "Caffè espresso",
                "bene_servizio": "B",
                "quantita": "2.00",
                "prezzo_unitario": "1.20",
                "sconto": "0.00",
                "iva": "10",
                "acconto_versato_beni_non_consegnati": false,
                "omaggio": false,
                "reso": 0
            }
        ]
    }
}

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Documento inesistente

{
    "success": false,
    "message": "Documento commerciale non trovato"
}

Reso DC

POST /api/pem/{serial_number}/fiscale/invio/reso

Scope richiesto ai client partner: fiscale:manage.

Emette il documento commerciale di reso, totale o parziale, e ne accoda la trasmissione al PEL. Per una vendita dello stesso PEM si indicano il suo progressivo e, per ogni riga resa, l'id della riga originale (da Recupera dati reso DC) con la quantita: il resto si prende dall'originale. Le righe di servizio non sono rendibili. Per un documento di un altro dispositivo si indicano matricola_reso, progressivo, dataOra e le righe complete. La risposta, come per Invio DC, è il PDF firmato del documento.

Parametri di percorso

Corpo della richiesta (application/json, obbligatorio)

Esempio:

{
    "idempotency_key": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "progressivo": "0012-0007",
    "elementi": [
        {
            "id": 5531,
            "quantita": "1"
        }
    ]
}

Risposte

• 200 — Il PDF firmato (PAdES) del documento emesso.

Corpo: application/pdf, binario.

• 401 — Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).

{
    "success": false,
    "message": "Il token di accesso è scaduto.",
    "error": "token_expired"
}

• 403 — Scope non concesso al client partner o ruolo non ammesso per l'operazione.

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 —

• 422 — Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application/json.

{
    "success": false,
    "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
    "errors": {
        "pagamenti": [
            "La somma degli importi dei pagamenti è inferiore al totale da pagare"
        ]
    }
}

• 502 — Il PEL non ha aperto la nuova giornata (JN004): il documento non è emesso, ripetere con la stessa idempotency_key.

{
    "error_code": "JN004",
    "message": "Errore apertura journal PEL: …"
}

Chiusura giornaliera

POST /api/pem/{serial_number}/fiscale/invio/chiusura

Scope richiesto ai client partner: fiscale:manage.

Chiude la giornata fiscale: scrive il blocco di chiusura del Journal e accoda l'invio firmato al PEL, che trasmette i corrispettivi all'AdE. La risposta arriva subito: l'esito si segue con Storico chiusure (inviato_il) e con le richieste di tipo CORRISPETTIVI. Se ci sono DC appena emessi ancora in invio al PEL la risposta è 409 JN005: riprovare dopo qualche istante. Una giornata aperta da 23 ore viene chiusa in automatico.

Parametri di percorso

Risposte

• 200 — success

{
    "success": true,
    "message": "Chiusura in elaborazione"
}

• 401 — Non autenticato

{
    "message": "Non hai i permessi per accedere a questa risorsa.",
    "error": "unauthenticated"
}

• 403 — Non autorizzato

{
    "success": false,
    "message": "Richiesta non autorizzata"
}

• 404 — Seriale inesistente o PEM non accessibile all'utente.

{
    "success": false,
    "message": "Il PEM specificato non è stato trovato."
}

• 409 —