{"openapi":"3.0.3","info":{"title":"BillyScontrinoSSW API Documentation","description":"","version":"1.0.0"},"servers":[{"url":"https:\/\/pem-staging.billyssw.it"}],"tags":[{"name":"Account - Registrazione","description":""},{"name":"Anagrafica - PEM","description":""},{"name":"Catalogo - ATECO","description":""},{"name":"Catalogo - Reparti","description":""},{"name":"Funzioni fiscali - Consultazione","description":""},{"name":"Funzioni fiscali - Controllo PEM","description":""},{"name":"Funzioni fiscali - Documenti gestionali","description":""},{"name":"Funzioni fiscali - Emergenza","description":""},{"name":"Funzioni fiscali - Opzione buoni pasto","description":""},{"name":"Funzioni fiscali - Richieste PEM","description":""},{"name":"Funzioni fiscali - Segnalazioni","description":""},{"name":"Funzioni fiscali - Stato PEM","description":""},{"name":"Funzioni fiscali - Trasmissioni","description":""}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"Il bearer \u00e8 un <b>access token<\/b> del realm Keycloak <code>billy<\/code>, ottenuto con Authorization Code + PKCE e il consenso dell'esercente. Per i client partner vale 10 minuti: alla scadenza (401 con <code>error: token_expired<\/code>) se ne chiede uno nuovo al token endpoint del realm con il <code>refresh_token<\/code>. Ogni endpoint dichiara lo scope richiesto ai client partner; quelli riservati all'app e al pannello Billy rispondono 403 a un client partner.","flows":{"authorizationCode":{"authorizationUrl":"https:\/\/auth.billyssw.it\/realms\/billy\/protocol\/openid-connect\/auth","tokenUrl":"https:\/\/auth.billyssw.it\/realms\/billy\/protocol\/openid-connect\/token","refreshUrl":"https:\/\/auth.billyssw.it\/realms\/billy\/protocol\/openid-connect\/token","scopes":{"fiscale:read":"Leggere lo stato dei PEM, consultare documenti commerciali e report","fiscale:manage":"Emettere documenti commerciali, annulli, resi e documenti gestionali, eseguire la chiusura giornaliera e di emergenza, gestire il PEM (cambio stato, dismissione, cambio sede, periodi di inattivit\u00e0)","catalogo:read":"Leggere reparti e codici ATECO","catalogo:write":"Creare, modificare ed eliminare reparti, categorie e codici ATECO","offline_access":"Refresh token di lunga durata (sessione offline)"}}}}},"schemas":{"Errore":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"}}},"ErroreAutenticazione":{"type":"object","required":["message","error"],"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"},"error":{"type":"string","enum":["token_expired","token_invalid","unauthenticated"]}}},"ErroreValidazione":{"type":"object","required":["success","message","errors"],"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"ErroreDominio":{"type":"object","required":["error_code","message"],"properties":{"error_code":{"type":"string"},"message":{"type":"string"}}}},"responses":{"NonAutenticato":{"description":"Token assente (error: unauthenticated), scaduto (error: token_expired) o non valido (error: token_invalid).","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErroreAutenticazione"},"example":{"success":false,"message":"Il token di accesso \u00e8 scaduto.","error":"token_expired"}}}},"NonAutorizzato":{"description":"Scope non concesso al client partner o ruolo non ammesso per l'operazione.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Errore"},"example":{"success":false,"message":"Richiesta non autorizzata"}}}},"PemNonTrovato":{"description":"Seriale inesistente o PEM non accessibile all'utente.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Errore"},"example":{"success":false,"message":"Il PEM specificato non \u00e8 stato trovato."}}}},"EsercenteNonTrovato":{"description":"Esercente inesistente o non accessibile all'utente.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Errore"},"example":{"success":false,"message":"L'esercente specificato non \u00e8 stato trovato."}}}},"ValidazioneNonRiuscita":{"description":"Dati non validi: errors riporta i messaggi per campo. Richiede Accept: application\/json.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErroreValidazione"},"example":{"success":false,"message":"La somma degli importi dei pagamenti \u00e8 inferiore al totale da pagare","errors":{"pagamenti":["La somma degli importi dei pagamenti \u00e8 inferiore al totale da pagare"]}}}}},"AperturaGiornataNonRiuscita":{"description":"Il PEL non ha aperto la nuova giornata (JN004): il documento non \u00e8 emesso, ripetere con la stessa idempotency_key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErroreDominio"},"example":{"error_code":"JN004","message":"Errore apertura journal PEL: \u2026"}}}}}},"security":[{"oauth2":[]}],"paths":{"\/api\/auth\/register":{"post":{"summary":"Richiesta di registrazione esercente","operationId":"richiestaDiRegistrazioneEsercente","description":"Registra la richiesta di adesione di un esercente, senza credenziali: la\nesamina l'erogatore e, all'approvazione, l'esercente riceve l'email per\nscegliere la password. `affiliate_code` \u00e8 il codice del partner che\nl'ha portato (`AFF-\u2026`), facoltativo.","parameters":[],"responses":{"200":{"description":"Richiesta registrata","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"Registrazione avvenuta con successo"},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Registrazione avvenuta con successo"}}}}}},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"},"429":{"description":"Troppe richieste","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Troppe richieste di registrazione: riprova tra qualche minuto","error":"too_many_requests"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Troppe richieste di registrazione: riprova tra qualche minuto"},"error":{"type":"string","example":"too_many_requests"}}}}}}},"tags":["Account - Registrazione"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","description":"Nome del titolare. Al massimo 60 caratteri.","example":"Mario"},"cognome":{"type":"string","description":"Cognome del titolare. Al massimo 60 caratteri.","example":"Rossi"},"email":{"type":"string","description":"Email del titolare, unica: \u00e8 l'indirizzo dell'account Billy ed \u00e8 anche il nome utente dell'account. Non si pu\u00f2 cambiare dopo l'approvazione. Deve essere un indirizzo email valido. Al massimo 80 caratteri.","example":"mario.rossi@example.it"},"telefono":{"type":"string","description":"Telefono, da 6 a 11 cifre; il prefisso +39 o 0039, gli spazi e i separatori vengono tolti. Formato: <code>\/^\\d{6,11}$\/<\/code>.","example":"3331234567"},"partita_iva":{"type":"string","description":"Partita IVA dell'attivit\u00e0, verificata e unica. Va inviata come stringa: un numero JSON perderebbe gli zeri iniziali ed \u00e8 rifiutato.","example":"01234567897"},"codice_fiscale":{"type":"string","description":"Codice fiscale dell'attivit\u00e0 o del titolare: 16 caratteri con carattere di controllo valido (omocodie ammesse, convertito in maiuscolo), oppure 11 cifre per le societ\u00e0, di solito uguali alla partita IVA.","example":"RSSMRA80A01F205X"},"denominazione":{"type":"string","description":"Denominazione dell'attivit\u00e0. Al massimo 80 caratteri.","example":"Bar Centrale di Mario Rossi"},"indirizzo":{"type":"string","description":"Indirizzo della sede legale. Al massimo 60 caratteri.","example":"Via Roma"},"civico":{"type":"string","description":"Numero civico della sede legale. Al massimo 8 caratteri.","example":"1"},"cap":{"type":"string","description":"CAP della sede legale, 5 cifre. Deve essere composto da 5 cifre.","example":"20121"},"comune":{"type":"string","description":"Comune della sede legale. Al massimo 60 caratteri.","example":"Milano"},"provincia":{"type":"string","description":"Sigla della provincia (elenco ISTAT; `EE` per l'estero). Deve essere lungo 2 caratteri.","example":"MI","enum":["AG","AL","AN","AO","AP","AQ","AR","AT","AV","BA","BG","BI","BL","BN","BO","BR","BS","BT","BZ","CA","CB","CE","CH","CL","CN","CO","CR","CS","CT","CZ","EN","FC","FE","FG","FI","FM","FR","GE","GO","GR","IM","IS","KR","LC","LE","LI","LO","LT","LU","MB","MC","ME","MI","MN","MO","MS","MT","NA","NO","NU","OR","PA","PC","PD","PE","PG","PI","PN","PO","PR","PT","PU","PV","PZ","RA","RC","RE","RG","RI","RM","RN","RO","SA","SI","SO","SP","SR","SS","SU","SV","TA","TE","TN","TO","TP","TR","TS","TV","UD","VA","VB","VC","VE","VI","VR","VT","VV","EE"]},"nazione":{"type":"string","description":"Codice della nazione, 2 caratteri. Deve essere lungo 2 caratteri.","example":"IT"},"pec":{"type":"string","description":"PEC dell'attivit\u00e0, facoltativa. Deve essere un indirizzo email valido. Al massimo 80 caratteri.","example":"barcentrale@pec.it","nullable":true},"sdi":{"type":"string","description":"Codice destinatario SDI, 7 lettere o cifre (convertito in maiuscolo), facoltativo. Formato: <code>\/^[A-Z0-9]{7}$\/<\/code>. Deve essere lungo 7 caratteri.","example":"M5UXCR1","nullable":true},"regime_fiscale":{"type":"string","description":"Regime fiscale dell'attivit\u00e0.","example":"ordinario","enum":["ordinario","semplificato","forfettario_minimo"]},"sede_operativa":{"type":"object","description":"Facoltativa: sede e referente del punto vendita, sede del primo PEM. Se manca, \u00e8 `null` o \u00e8 vuota vale la sede legale con i dati del titolare.","properties":{"nome_referente":{"type":"string","description":"Al massimo 60 caratteri.","example":"Mario"},"cognome_referente":{"type":"string","description":"Al massimo 60 caratteri.","example":"Rossi"},"email_referente":{"type":"string","description":"Deve essere un indirizzo email valido. Al massimo 80 caratteri.","example":"mario.rossi@example.it"},"telefono_referente":{"type":"string","description":"Formato: <code>\/^\\d{6,11}$\/<\/code>.","example":"3331234567"},"indirizzo":{"type":"string","description":"Al massimo 60 caratteri.","example":"Corso Buenos Aires"},"civico":{"type":"string","description":"Al massimo 8 caratteri.","example":"10"},"cap":{"type":"string","description":"Deve essere composto da 5 cifre.","example":"20124"},"comune":{"type":"string","description":"Al massimo 60 caratteri.","example":"Milano"},"provincia":{"type":"string","description":"Deve essere lungo 2 caratteri.","example":"MI","enum":["AG","AL","AN","AO","AP","AQ","AR","AT","AV","BA","BG","BI","BL","BN","BO","BR","BS","BT","BZ","CA","CB","CE","CH","CL","CN","CO","CR","CS","CT","CZ","EN","FC","FE","FG","FI","FM","FR","GE","GO","GR","IM","IS","KR","LC","LE","LI","LO","LT","LU","MB","MC","ME","MI","MN","MO","MS","MT","NA","NO","NU","OR","PA","PC","PD","PE","PG","PI","PN","PO","PR","PT","PU","PV","PZ","RA","RC","RE","RG","RI","RM","RN","RO","SA","SI","SO","SP","SR","SS","SU","SV","TA","TE","TN","TO","TP","TR","TS","TV","UD","VA","VB","VC","VE","VI","VR","VT","VV","EE"]},"nazione":{"type":"string","description":"Deve essere lungo 2 caratteri.","example":"IT"}},"required":["nome_referente","cognome_referente","email_referente","telefono_referente","indirizzo","civico","cap","comune","provincia","nazione"],"nullable":true},"affiliate_code":{"type":"string","description":"Codice del partner affiliato che ha portato l'esercente, facoltativo. Al massimo 32 caratteri.","example":"AFF-7K2M9QXA","nullable":true},"privacy":{"type":"boolean","description":"Accettazione dell'informativa privacy. Deve valere true.","example":true}},"required":["nome","cognome","email","telefono","partita_iva","codice_fiscale","denominazione","indirizzo","civico","cap","comune","provincia","nazione","regime_fiscale","privacy"],"example":{"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}}}}},"security":[],"x-billy-accesso":{"tipo":"pubblico"}}},"\/api\/pem":{"get":{"summary":"Lista PEM","operationId":"listaPEM","description":"Mostra la lista dei PEM associati all'utente autenticato.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"pem":[{"id":1,"serial_number":"ASVS-241232","stato":"In servizio","created_at":"01-01-2025 13:00:00","indirizzo":"Via Roma 1"}]},"properties":{"success":{"type":"boolean","example":true},"pem":{"type":"array","example":[{"id":1,"serial_number":"ASVS-241232","stato":"In servizio","created_at":"01-01-2025 13:00:00","indirizzo":"Via Roma 1"}],"items":{"type":"object","properties":{"id":{"type":"integer","example":1},"serial_number":{"type":"string","example":"ASVS-241232"},"stato":{"type":"string","example":"In servizio"},"created_at":{"type":"string","example":"01-01-2025 13:00:00"},"indirizzo":{"type":"string","example":"Via Roma 1"}}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}}},"tags":["Anagrafica - PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]}},"\/api\/pem\/{serial_number}":{"get":{"summary":"Mostra PEM","operationId":"mostraPEM","description":"Mostra i dettagli del PEM indicato.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"pem":{"id":1,"serial_number":"ASVS-241232","stato":"In servizio","created_at":"01-01-2025 13:00:00","indirizzo":"Via Roma 1"}},"properties":{"success":{"type":"boolean","example":true},"pem":{"type":"object","properties":{"id":{"type":"integer","example":1},"serial_number":{"type":"string","example":"ASVS-241232"},"stato":{"type":"string","example":"In servizio"},"created_at":{"type":"string","example":"01-01-2025 13:00:00"},"indirizzo":{"type":"string","example":"Via Roma 1"}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Anagrafica - PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/cambio-sede":{"post":{"summary":"Richiedi il cambio sede","operationId":"richiediIlCambioSede","description":"Chiede di spostare il PEM a un nuovo indirizzo. Se serve l'approvazione\ndell'erogatore la richiesta resta in attesa; una volta approvata l'emissione\n\u00e8 sospesa fino alla chiusura di giornata e la nuova sede vale dalla prima\nemissione successiva.","parameters":[],"responses":{"200":{"description":"Richiesta registrata","content":{"application\/json":{"example":{"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\u00e0 sospesa fino alla chiusura di giornata, poi la nuova sede sar\u00e0 applicata automaticamente alla prima emissione"}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"}},"tags":["Anagrafica - PEM"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"indirizzo":{"type":"string","description":"Al massimo 60 caratteri.","example":"Via Garibaldi"},"civico":{"type":"string","description":"Al massimo 8 caratteri.","example":"12"},"cap":{"type":"string","description":"Deve essere composto da 5 cifre.","example":"20121"},"comune":{"type":"string","description":"Al massimo 60 caratteri.","example":"Milano"},"provincia":{"type":"string","description":"Deve essere lungo 2 caratteri.","example":"MI"},"nazione":{"type":"string","description":"Al massimo 2 caratteri.","example":"IT"},"sede_legale":{"type":"boolean","description":"","example":false}},"required":["indirizzo","civico","cap","comune","provincia","nazione","sede_legale"],"example":{"indirizzo":"Via Garibaldi","civico":"12","cap":"20121","comune":"Milano","provincia":"MI","nazione":"IT","sede_legale":false}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/cambio-sede\/{cambio_sede}":{"delete":{"summary":"Annulla il cambio sede","operationId":"annullaIlCambioSede","description":"Ritira una richiesta di cambio sede non ancora applicata (409 se non \u00e8 pi\u00f9 annullabile).","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"Richiesta di cambio sede annullata"},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Richiesta di cambio sede annullata"}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Anagrafica - PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}},{"in":"path","name":"cambio_sede","description":"L'id della richiesta di cambio sede.","example":4,"required":true,"schema":{"type":"integer"}}]},"\/api\/pem\/{serial_number}\/dati\/ateco":{"get":{"summary":"Lista ATECO","operationId":"listaATECO","description":"Restituisce i codici ATECO associati al PEM indicato.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"ateco":[{"id":1,"codice":"112233","descrizione":"TEST ATECO"}]},"properties":{"success":{"type":"boolean","example":true},"ateco":{"type":"array","example":[{"id":1,"codice":"112233","descrizione":"TEST ATECO"}],"items":{"type":"object","properties":{"id":{"type":"integer","example":1},"codice":{"type":"string","example":"112233"},"descrizione":{"type":"string","example":"TEST ATECO"}}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Catalogo - ATECO"],"x-billy-accesso":{"tipo":"partner","scope":["catalogo:read"]},"security":[{"oauth2":["catalogo:read"]}]},"post":{"summary":"Crea ATECO","operationId":"creaATECO","description":"Crea un nuovo codice ATECO associato al PEM indicato.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"ATECO creato con successo","ateco":{"id":1,"codice":"112233","descrizione":"TEST ATECO"}},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"ATECO creato con successo"},"ateco":{"type":"object","properties":{"id":{"type":"integer","example":1},"codice":{"type":"string","example":"112233"},"descrizione":{"type":"string","example":"TEST ATECO"}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"description":"Validazione fallita","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Il campo codice \u00e8 obbligatorio","errors":{"ateco.codice":["Il campo codice \u00e8 obbligatorio"]}},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Il campo codice \u00e8 obbligatorio"},"errors":{"type":"object","properties":{"ateco.codice":{"type":"array","example":["Il campo codice \u00e8 obbligatorio"],"items":{"type":"string"}}}}}}}}}},"tags":["Catalogo - ATECO"],"requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"ateco":{"type":"object","description":"","properties":{"descrizione":{"type":"string","description":"La descrizione dell'ATECO. Al massimo 100 caratteri.","example":"Commercio al dettaglio"},"codice":{"type":"string","description":"Il codice ATECO nel formato XX.XX.XX. Unico sul PEM. Formato: <code>\/^\\d{2}\\.\\d{2}\\.\\d{2}$\/<\/code>.","example":"47.11.00"}},"required":["descrizione","codice"]}},"example":{"ateco":{"descrizione":"Commercio al dettaglio","codice":"47.11.00"}}}}}},"x-billy-accesso":{"tipo":"partner","scope":["catalogo:write"]},"security":[{"oauth2":["catalogo:write"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/dati\/ateco\/{id}":{"put":{"summary":"Aggiorna ATECO","operationId":"aggiornaATECO","description":"Aggiorna un codice ATECO esistente associato al PEM indicato.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"ATECO aggiornato con successo","ateco":{"id":1,"codice":"112233","descrizione":"TEST ATECO"}},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"ATECO aggiornato con successo"},"ateco":{"type":"object","properties":{"id":{"type":"integer","example":1},"codice":{"type":"string","example":"112233"},"descrizione":{"type":"string","example":"TEST ATECO"}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"description":"ATECO non trovato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"La risorsa richiesta non \u00e8 stata trovata."},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"La risorsa richiesta non \u00e8 stata trovata."}}}}}},"422":{"description":"Validazione fallita","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Il campo codice \u00e8 obbligatorio","errors":{"ateco.codice":["Il campo codice \u00e8 obbligatorio"]}},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Il campo codice \u00e8 obbligatorio"},"errors":{"type":"object","properties":{"ateco.codice":{"type":"array","example":["Il campo codice \u00e8 obbligatorio"],"items":{"type":"string"}}}}}}}}}},"tags":["Catalogo - ATECO"],"requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"ateco":{"type":"object","description":"","properties":{"descrizione":{"type":"string","description":"La descrizione dell'ATECO. Al massimo 100 caratteri.","example":"Commercio al dettaglio"},"codice":{"type":"string","description":"Il codice ATECO nel formato XX.XX.XX. Unico sul PEM. Formato: <code>\/^\\d{2}\\.\\d{2}\\.\\d{2}$\/<\/code>.","example":"47.11.00"}}}},"example":{"ateco":{"descrizione":"Commercio al dettaglio","codice":"47.11.00"}}}}}},"x-billy-accesso":{"tipo":"partner","scope":["catalogo:write"]},"security":[{"oauth2":["catalogo:write"]}]},"delete":{"summary":"Elimina ATECO","operationId":"eliminaATECO","description":"Elimina un codice ATECO associato al PEM indicato.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"ATECO eliminato con successo"},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"ATECO eliminato con successo"}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"description":"ATECO non trovato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"La risorsa richiesta non \u00e8 stata trovata."},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"La risorsa richiesta non \u00e8 stata trovata."}}}}}}},"tags":["Catalogo - ATECO"],"x-billy-accesso":{"tipo":"partner","scope":["catalogo:write"]},"security":[{"oauth2":["catalogo:write"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","description":"L'ID dell'ATECO.","example":23,"required":true,"schema":{"type":"integer"}}]},"\/api\/pem\/{serial_number}\/dati\/reparti":{"get":{"summary":"Lista Reparti","operationId":"listaReparti","description":"Mostra la lista dei reparti associati al PEM corrente.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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}]},"properties":{"success":{"type":"boolean","example":true},"reparti":{"type":"array","example":[{"id":1,"sigla":"R1","descrizione":"Reparto 1","importo":100,"iva":"22","colore":"#FFFFFF","bene_servizio":"B","id_categoria":1,"id_ateco":1}],"items":{"type":"object","properties":{"id":{"type":"integer","example":1},"sigla":{"type":"string","example":"R1"},"descrizione":{"type":"string","example":"Reparto 1"},"importo":{"type":"number","example":100},"iva":{"type":"string","example":"22"},"colore":{"type":"string","example":"#FFFFFF"},"bene_servizio":{"type":"string","example":"B"},"id_categoria":{"type":"integer","example":1},"id_ateco":{"type":"integer","example":1}}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Catalogo - Reparti"],"x-billy-accesso":{"tipo":"partner","scope":["catalogo:read"]},"security":[{"oauth2":["catalogo:read"]}]},"post":{"summary":"Crea Reparto","operationId":"creaReparto","description":"Memorizza un nuovo reparto associato al PEM corrente.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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}},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Reparto creato con successo"},"reparto":{"type":"object","properties":{"id":{"type":"integer","example":1},"sigla":{"type":"string","example":"R1"},"descrizione":{"type":"string","example":"Reparto 1"},"importo":{"type":"number","example":100},"iva":{"type":"string","example":"22"},"colore":{"type":"string","example":"#FFFFFF"},"bene_servizio":{"type":"string","example":"B"},"id_categoria":{"type":"integer","example":1},"id_ateco":{"type":"integer","example":1}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"description":"Validazione fallita","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Il campo iva \u00e8 obbligatorio","errors":{"reparto.iva":["Il campo iva \u00e8 obbligatorio"]}},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Il campo iva \u00e8 obbligatorio"},"errors":{"type":"object","properties":{"reparto.iva":{"type":"array","example":["Il campo iva \u00e8 obbligatorio"],"items":{"type":"string"}}}}}}}}}},"tags":["Catalogo - Reparti"],"requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"reparto":{"type":"object","description":"","properties":{"sigla":{"type":"string","description":"La sigla del reparto. Al massimo 20 caratteri.","example":"A"},"codice":{"type":"string","description":"Il codice del reparto. Al massimo 50 caratteri.","example":"REP-001","nullable":true},"descrizione":{"type":"string","description":"La descrizione del reparto. Al massimo 100 caratteri.","example":"Caffetteria"},"importo":{"type":"number","description":"L'importo del reparto.","example":1.2},"iva":{"type":"string","description":"L'aliquota IVA del reparto.","example":"10","enum":["4","5","10","22","N1","N2","N3","N4","N5","N6","VI"]},"colore":{"type":"string","description":"Il colore del reparto. Formato: <code>\/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$\/<\/code>.","example":"#FFFFFF"},"bene_servizio":{"type":"string","description":"Il tipo di bene\/servizio del reparto.","example":"B","enum":["B","S"]},"id_categoria":{"type":"number","description":"L'ID della categoria del reparto.","example":1,"nullable":true},"id_ateco":{"type":"number","description":"L'ID dell'ATECO del reparto.","example":1,"nullable":true}},"required":["sigla","descrizione","importo","iva","bene_servizio"]}},"example":{"reparto":{"sigla":"A","descrizione":"Caffetteria","importo":1.2,"iva":"10","bene_servizio":"B"}}}}}},"x-billy-accesso":{"tipo":"partner","scope":["catalogo:write"]},"security":[{"oauth2":["catalogo:write"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/dati\/reparti\/{reparto_id}":{"put":{"summary":"Aggiorna Reparto","operationId":"aggiornaReparto","description":"Aggiorna un reparto esistente associato al PEM indicato.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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}},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Reparto aggiornato con successo"},"reparto":{"type":"object","properties":{"id":{"type":"integer","example":1},"sigla":{"type":"string","example":"R1"},"descrizione":{"type":"string","example":"Reparto 1"},"importo":{"type":"number","example":100},"iva":{"type":"string","example":"22"},"colore":{"type":"string","example":"#FFFFFF"},"bene_servizio":{"type":"string","example":"B"},"id_categoria":{"type":"integer","example":1},"id_ateco":{"type":"integer","example":1}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"description":"Reparto non trovato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"La risorsa richiesta non \u00e8 stata trovata."},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"La risorsa richiesta non \u00e8 stata trovata."}}}}}},"422":{"description":"Validazione fallita","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Aliquota non valida","errors":{"reparto.iva":["Aliquota non valida"]}},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Aliquota non valida"},"errors":{"type":"object","properties":{"reparto.iva":{"type":"array","example":["Aliquota non valida"],"items":{"type":"string"}}}}}}}}}},"tags":["Catalogo - Reparti"],"requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"reparto":{"type":"object","description":"","properties":{"sigla":{"type":"string","description":"La sigla del Reparto. Al massimo 20 caratteri.","example":"A"},"codice":{"type":"string","description":"Il codice del Reparto. Al massimo 50 caratteri.","example":"REP-001","nullable":true},"descrizione":{"type":"string","description":"La descrizione del Reparto. Al massimo 100 caratteri.","example":"Caffetteria"},"importo":{"type":"number","description":"L'importo del Reparto.","example":1.2},"iva":{"type":"string","description":"L'IVA del Reparto.","example":"10","enum":["4","5","10","22","N1","N2","N3","N4","N5","N6","VI"]},"colore":{"type":"string","description":"Il colore del Reparto in esadecimale. Formato: <code>\/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$\/<\/code>.","example":"#FFFFFF"},"ordine":{"type":"number","description":"L'ordine del Reparto.","example":1},"bene_servizio":{"type":"string","description":"Il tipo di Bene\/Servizio del Reparto.","example":"B","enum":["B","S"]},"preferito":{"type":"boolean","description":"Indica se il Reparto \u00e8 preferito.","example":true},"id_categoria":{"type":"number","description":"L'ID della Categoria del Reparto.","example":1,"nullable":true},"id_ateco":{"type":"number","description":"L'ID dell'ATECO del Reparto.","example":1,"nullable":true}}}},"example":{"reparto":{"sigla":"A","descrizione":"Caffetteria","importo":1.2,"iva":"10","bene_servizio":"B"}}}}}},"x-billy-accesso":{"tipo":"partner","scope":["catalogo:write"]},"security":[{"oauth2":["catalogo:write"]}]},"delete":{"summary":"Elimina Reparto","operationId":"eliminaReparto","description":"Elimina un reparto associato al PEM indicato.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"Reparto eliminato con successo"},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Reparto eliminato con successo"}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"description":"Reparto non trovato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"La risorsa richiesta non \u00e8 stata trovata."},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"La risorsa richiesta non \u00e8 stata trovata."}}}}}}},"tags":["Catalogo - Reparti"],"x-billy-accesso":{"tipo":"partner","scope":["catalogo:write"]},"security":[{"oauth2":["catalogo:write"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}},{"in":"path","name":"reparto_id","description":"L'ID del reparto.","example":23,"required":true,"schema":{"type":"integer"}}]},"\/api\/pem\/{serial_number}\/fiscale\/chiusure\/storico":{"get":{"summary":"Storico chiusure","operationId":"storicoChiusure","description":"Elenca le giornate chiuse del PEM, dalla pi\u00f9 recente, con il numero di DC\ne la data di trasmissione al PEL (`inviato_il` nullo = chiusura non ancora\ntrasmessa). `journal_aperto` \u00e8 la giornata in corso, nullo se la cassa \u00e8 chiusa.\n`data_chiusura` \u00e8 in ora locale; `inviato_il` e `aperto_il` in UTC.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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"}},"properties":{"success":{"type":"boolean","example":true},"chiusure":{"type":"array","example":[{"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"}],"items":{"type":"object","properties":{"id":{"type":"integer","example":12},"progressivo":{"type":"integer","example":12},"data_chiusura":{"type":"string","example":"2026-10-07T21:30:00"},"numero_dc":{"type":"integer","example":48},"numero_dc_journal":{"type":"integer","example":48},"inviato_il":{"type":"string","example":"2026-10-07T19:30:04.000000Z"}}}},"journal_aperto":{"type":"object","properties":{"id":{"type":"integer","example":13},"progressivo":{"type":"integer","example":13},"aperto_il":{"type":"string","example":"2026-10-08T06:02:11.000000Z"}}}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Funzioni fiscali - Consultazione"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/chiusure\/{journalId}\/documento":{"get":{"summary":"Dati di una chiusura","operationId":"datiDiUnaChiusura","description":"Restituisce i dati della giornata fiscale chiusa (`journalId` da *Storico\nchiusure*): dati locali della chiusura uniti ai totali del PEL, unica fonte\nfiscale. Finch\u00e9 la chiusura non \u00e8 stata trasmessa all'AdE il PEL non ha i\ntotali e la risposta \u00e8 409.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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}}},"properties":{"success":{"type":"boolean","example":true},"documento":{"type":"object","properties":{"pem":{"type":"object","properties":{"serial_number":{"type":"string","example":"ASVS-241232"},"indirizzo":{"type":"string","example":"Via Roma 1"},"comune":{"type":"string","example":"Milano"},"cap":{"type":"string","example":"20100"},"provincia":{"type":"string","example":"MI"}}},"esercente":{"type":"object","properties":{"denominazione":{"type":"string","example":"Bar Centrale srl"},"partita_iva":{"type":"string","example":"01234567890"}}},"journal":{"type":"object","properties":{"progressivo":{"type":"integer","example":12},"data_chiusura":{"type":"string","example":"2026-10-07T21:30:00"},"numero_dc":{"type":"integer","example":48},"numero_dc_journal":{"type":"integer","example":48}}},"riepilogo":{"type":"object","properties":[]},"pagamenti":{"type":"object","properties":[]},"riepiloghi":{"type":"array","example":[]},"chiusure":{"type":"array","example":[]},"buoni_pasto":{"type":"object","properties":{"attiva":{"type":"boolean","example":false},"aggiornato_il":{"type":"string","example":null,"nullable":true}}}}}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"409":{"description":"Corrispettivi non trasmessi","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Chiusura non ancora trasmessa all'AdE"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Chiusura non ancora trasmessa all'AdE"}}}}}}},"tags":["Funzioni fiscali - Consultazione"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}},{"in":"path","name":"journalId","description":"L'id della chiusura (campo `id` dello storico).","example":12,"required":true,"schema":{"type":"integer"}}]},"\/api\/pem\/{serial_number}\/fiscale\/consultazione\/report":{"post":{"summary":"Report","operationId":"report","description":"Elabora il report delle vendite del PEM indicato","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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}},"properties":{"success":{"type":"boolean","example":true},"scontrini":{"type":"array","example":[{"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="}],"items":{"type":"object","properties":{"id":{"type":"integer","example":102},"user":{"type":"string","example":"EsercenteTEST"},"tipo":{"type":"string","example":"DC"},"progressivo":{"type":"string","example":"0089-0001"},"data":{"type":"string","example":"2025-07-22 14:58:57"},"inviato_il":{"type":"string","example":"2025-07-22 14:59:02"},"importo":{"type":"number","example":377.5},"pagamenti_metodo":{"type":"string","example":"PC"},"progressivo_riferimento":{"type":"string","example":null,"nullable":true},"annullato":{"type":"boolean","example":false},"reso_fatto":{"type":"boolean","example":false},"hash":{"type":"string","example":"NmNhMzI5MDc3NjY2YzI5OTk2NDBiODg5YmFhMjEyMDI3MzZlZmNiNTMzMjEzNDQxNDE1YzQ1MmZlYWMyMjYyZTlmMTljMWVkYzFmN2UzMGU2ODYxMGIxMzVjZmJiMDBjNDAwMDI5NmQ5YTk1ODk4ZDI4NWQ3NmU1MjI5ZTkwMzg="}}}},"totali":{"type":"object","properties":{"totaleLordo":{"type":"number","example":377.5},"totaleAnnulli":{"type":"integer","example":0},"totaleResi":{"type":"integer","example":0},"pagamenti":{"type":"object","properties":{"contanti":{"type":"integer","example":377},"elettronico":{"type":"integer","example":0},"ticket":{"type":"integer","example":0},"nonRiscossoBeni":{"type":"integer","example":0},"nonRiscossoServizi":{"type":"integer","example":0},"nonRiscossoFattura":{"type":"integer","example":0},"scontoAPagare":{"type":"integer","example":0}}},"iva":{"type":"object","properties":{"10":{"type":"object","properties":{"imponibile":{"type":"number","example":70.45454545},"importo":{"type":"number","example":7.04545455}}},"N2":{"type":"object","properties":{"imponibile":{"type":"integer","example":100},"importo":{"type":"integer","example":0}}},"N4":{"type":"object","properties":{"imponibile":{"type":"integer","example":200},"importo":{"type":"integer","example":0}}}}},"reparto":{"type":"object","properties":{"Nessuno":{"type":"number","example":377.5}}},"totaleOmaggi":{"type":"integer","example":0}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"}},"tags":["Funzioni fiscali - Consultazione"],"requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"data_inizio":{"type":"string","description":"Data di inizio del periodo di report. Deve essere una data valida.","example":"2026-10-01"},"data_fine":{"type":"string","description":"Data di fine del periodo di report. Deve essere una data valida.","example":"2026-10-31"},"metodi_pagamento":{"type":"array","description":"Metodo di pagamento da filtrare, con i codici di emissione (PC, PP, TK, NRF, NRB, NRS, NRD).","example":["PP"],"items":{"type":"string"}},"utenti":{"type":"array","description":"ID utente specifico da filtrare.","example":[121],"items":{"type":"integer"}},"tipo_documenti":{"type":"array","description":"Tipo di documento da filtrare: DC (vendita), ANNULLO o RESO.","example":["DC"],"items":{"type":"string"}},"ricerca":{"type":"string","description":"Testo libero per filtrare per progressivo DC (es. '0089-0001') o per descrizione di un elemento contabile. Al massimo 255 caratteri.","example":"0089","nullable":true}},"example":{"data_inizio":"2026-10-01","data_fine":"2026-10-31"}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/consultazione\/dc":{"get":{"summary":"Dettaglio di un DC","operationId":"dettaglioDiUnDC","description":"Restituisce un documento commerciale del PEM nello stesso formato della\nrisposta di emissione: con `id` quello indicato, senza l'ultimo emesso\ndall'utente del token.","parameters":[{"in":"query","name":"id","description":"L'id del documento commerciale (dal report).","example":1532,"required":false,"schema":{"type":"integer","description":"L'id del documento commerciale (dal report).","example":1532}}],"responses":{"200":{"description":"Il documento commerciale (abbreviato)","content":{"application\/json":{"example":{"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\u00e8 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":{"description":"","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Il token di accesso non \u00e8 valido.","error":"token_invalid"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Il token di accesso non \u00e8 valido."},"error":{"type":"string","example":"token_invalid"}}}}}},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"description":"Documento inesistente","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"errore":"Documento commerciale non trovato"},"properties":{"success":{"type":"boolean","example":false},"errore":{"type":"string","example":"Documento commerciale non trovato"}}}}}}},"tags":["Funzioni fiscali - Consultazione"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/controllo":{"get":{"summary":"Dati di controllo AdE del PEM","operationId":"datiDiControlloAdEDelPEM","description":"Restituisce i dati identificativi, di stato e di versione richiesti per il controllo del PEM.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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}}},"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"matricola":{"type":"string","example":"ASVS-000001"},"stato":{"type":"string","example":"In servizio"},"data_cambio_stato":{"type":"string","example":"01-01-2025 10:00:00"},"esercente":{"type":"object","properties":{"partita_iva":{"type":"string","example":"12345678901"},"codice_fiscale":{"type":"string","example":"RSSMRA80A01H501Z"},"denominazione":{"type":"string","example":"Esercente Srl"}}},"erogatore":{"type":"object","properties":{"partita_iva":{"type":"string","example":"12345678901"},"codice_fiscale":{"type":"string","example":"RSSMRA80A01H501Z"},"denominazione":{"type":"string","example":"Erogatore Srl"}}},"soluzione_software":{"type":"object","properties":{"sigla":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"id_approvazione":{"type":"string","example":"0000"},"data_approvazione":{"type":"string","example":null,"nullable":true}}},"versione_installata":{"type":"object","properties":{"versione":{"type":"integer","example":1},"sotto_versione":{"type":"integer","example":0},"patch":{"type":"string","example":"0"},"data_ora":{"type":"string","example":"01-01-2025 10:00:00"},"swid":{"type":"string","example":null,"nullable":true}}},"versione_disponibile":{"type":"object","properties":{"versione":{"type":"integer","example":1},"sotto_versione":{"type":"integer","example":0},"patch":{"type":"string","example":"0"},"data_creazione":{"type":"string","example":"01-01-2025 10:00:00"},"data_approvazione":{"type":"string","example":null,"nullable":true},"swid":{"type":"string","example":null,"nullable":true}}},"dc_non_trasmessi":{"type":"object","properties":{"count":{"type":"integer","example":3},"importo_totale":{"type":"number","example":125.5}}}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa."},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"description":"PEM non trovato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Il PEM specificato non \u00e8 stato trovato."},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Il PEM specificato non \u00e8 stato trovato."}}}}}}},"tags":["Funzioni fiscali - Controllo PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/gestionali\/controllo":{"post":{"summary":"Emetti Documento Gestionale di Controllo","operationId":"emettiDocumentoGestionaleDiControllo","description":"Genera il PDF dei dati di controllo del PEM lato backend e lo archivia\ncome Documento Gestionale (tipo `controllo`), restituendolo in download.","parameters":[],"responses":{"200":{"description":"Il PDF firmato del documento gestionale.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento gestionale.","schema":{"type":"string","example":"attachment; filename=\"documento_gestionale_0012-0001.pdf\""}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa."},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."}}}}}},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"description":"PEM non trovato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Il PEM specificato non \u00e8 stato trovato."},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Il PEM specificato non \u00e8 stato trovato."}}}}}},"409":{"description":"Nessun Journal aperto","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Nessun Journal aperto disponibile"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Nessun Journal aperto disponibile"}}}}}}},"tags":["Funzioni fiscali - Controllo PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/gestionali":{"get":{"summary":"Archivio documenti gestionali","operationId":"archivioDocumentiGestionali","description":"Elenca i documenti gestionali del PEM, di qualunque tipo, filtrabili per\ndata di elaborazione e per tipo. Senza `Accept: application\/json` rende la\npagina Inertia dell'archivio.","parameters":[{"in":"query","name":"data","description":"Filtra per data di elaborazione.","example":"2026-08-20","required":false,"schema":{"type":"string","description":"Filtra per data di elaborazione.","example":"2026-08-20"}},{"in":"query","name":"tipo","description":"Filtra per tipo di documento gestionale.","example":"operazioni","required":false,"schema":{"type":"string","description":"Filtra per tipo di documento gestionale.","example":"operazioni","enum":["chiusura","controllo","operazioni","esiti_trasmissione","storico_buoni_pasto"]}}],"responses":{"200":{"description":"I documenti gestionali del PEM, dal pi\u00f9 recente","content":{"application\/json":{"example":{"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":{"description":"","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Il token di accesso non \u00e8 valido.","error":"token_invalid"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Il token di accesso non \u00e8 valido."},"error":{"type":"string","example":"token_invalid"}}}}}},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Funzioni fiscali - Documenti gestionali"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/gestionali\/{id}\/pdf":{"get":{"summary":"Download di un documento gestionale archiviato","operationId":"downloadDiUnDocumentoGestionaleArchiviato","description":"Restituisce il PDF firmato gi\u00e0 emesso, qualunque ne sia il tipo.","parameters":[],"responses":{"200":{"description":"Il PDF firmato del documento gestionale.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento gestionale.","schema":{"type":"string","example":"attachment; filename=\"documento_gestionale_0012-0001.pdf\""}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Il token di accesso non \u00e8 valido.","error":"token_invalid"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Il token di accesso non \u00e8 valido."},"error":{"type":"string","example":"token_invalid"}}}}}},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"description":"Non trovato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Documento gestionale non trovato"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Documento gestionale non trovato"}}}}}}},"tags":["Funzioni fiscali - Documenti gestionali"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","description":"L'id del documento gestionale (dall'archivio).","example":5,"required":true,"schema":{"type":"integer"}}]},"\/api\/pem\/{serial_number}\/fiscale\/gestionali\/operazioni":{"post":{"summary":"Documento gestionale operazioni memorizzate","operationId":"documentoGestionaleOperazioniMemorizzate","description":"Emette e restituisce il documento gestionale con le operazioni memorizzate\ndal PEM secondo la chiave di selezione indicata (ST v1.4 \u00a73.4.2, punti 1-4).\nLa selezione `integrale` produce il solo riepilogo; le selezioni delimitate\nincludono anche il dettaglio per documento e gli aggregati giornalieri.","parameters":[],"responses":{"200":{"description":"Il PDF firmato del documento gestionale.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento gestionale.","schema":{"type":"string","example":"attachment; filename=\"documento_gestionale_0012-0001.pdf\""}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"409":{"description":"Cassa chiusa","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Nessun Journal aperto disponibile"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Nessun Journal aperto disponibile"}}}}}},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"}},"tags":["Funzioni fiscali - Documenti gestionali"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"selezione":{"type":"string","description":"Chiave di selezione: `integrale` (tutto l'archivio, solo riepilogo), `date` (tra due date), `documento` (per numero di documento), `intervallo` (tra due numeri di documento dello stesso journal).","example":"date","enum":["integrale","date","documento","intervallo"]},"data_inizio":{"type":"string","description":"Data di inizio del periodo. Obbligatoria con `selezione=date`. Deve essere una data valida.","example":"2026-10-01"},"data_fine":{"type":"string","description":"Data di fine del periodo. Obbligatoria con `selezione=date`. Deve essere una data valida. Deve essere una data uguale o successiva a <code>data_inizio<\/code>.","example":"2026-10-08"},"progressivo":{"type":"string","description":"Numero del documento in forma `NNNN-PPPP`. Obbligatorio con `selezione=documento`. Al massimo 32 caratteri.","example":"0089-0001"},"journal":{"type":"integer","description":"Progressivo del journal (`NNNN`). Obbligatorio con `selezione=intervallo`. Almeno 1.","example":89},"progressivo_da":{"type":"integer","description":"Progressivo iniziale del documento (`PPPP`). Obbligatorio con `selezione=intervallo`. Almeno 1. Al massimo 9999.","example":1},"progressivo_a":{"type":"integer","description":"Progressivo finale del documento (`PPPP`). Obbligatorio con `selezione=intervallo`. Al massimo 9999.","example":50},"metodi_pagamento":{"type":"array","description":"Metodo di pagamento specifico da filtrare (es. \"PC\" per contanti, \"PP\" per pagamento elettronico).","example":["PP"],"items":{"type":"string"}},"utenti":{"type":"array","description":"ID utente specifico da filtrare.","example":[121],"items":{"type":"integer"}},"tipo_documenti":{"type":"array","description":"Tipo di documento specifico da filtrare (es. \"DC\", \"A\" per annullo, \"R\" per reso).","example":["DC"],"items":{"type":"string"}},"ateco":{"type":"array","description":"Codice ATECO specifico da filtrare.","example":["011101"],"items":{"type":"string"}},"ricerca":{"type":"string","description":"Testo libero su progressivo DC (es. '0089-0001') o descrizione di un elemento contabile. Al massimo 255 caratteri.","example":"0089","nullable":true}},"required":["selezione"],"example":{"selezione":"date","data_inizio":"2026-10-01","data_fine":"2026-10-08"}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/gestionali\/esiti-trasmissione":{"post":{"summary":"Documento gestionale esiti trasmissioni corrispettivi","operationId":"documentoGestionaleEsitiTrasmissioniCorrispettivi","description":"Emette e restituisce il documento gestionale con gli esiti delle\ntrasmissioni dei corrispettivi comprese tra due date (ST v1.4 \u00a73.4.2,\npunto 5). I dati provengono da `richieste_pem`: nessuna chiamata al PEL.","parameters":[],"responses":{"200":{"description":"Il PDF firmato del documento gestionale.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento gestionale.","schema":{"type":"string","example":"attachment; filename=\"documento_gestionale_0012-0001.pdf\""}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"409":{"description":"Cassa chiusa","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Nessun Journal aperto disponibile"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Nessun Journal aperto disponibile"}}}}}},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"}},"tags":["Funzioni fiscali - Documenti gestionali"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"data_inizio":{"type":"string","description":"Data di inizio dell'intervallo di trasmissioni. Deve essere una data valida.","example":"2026-01-01"},"data_fine":{"type":"string","description":"Data di fine dell'intervallo di trasmissioni. Deve essere una data valida. Deve essere una data uguale o successiva a <code>data_inizio<\/code>.","example":"2026-08-20"}},"required":["data_inizio","data_fine"],"example":{"data_inizio":"2026-01-01","data_fine":"2026-08-20"}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/gestionali\/storico-buoni-pasto":{"post":{"summary":"Documento gestionale storico opzione buoni pasto","operationId":"documentoGestionaleStoricoOpzioneBuoniPasto","description":"Emette e restituisce il documento gestionale con lo storico delle\nattivazioni e disattivazioni dell'opzione buoni pasto (ST v1.4 \u00a73.4.2,\npunto 8). Nessun parametro di selezione.","parameters":[],"responses":{"200":{"description":"Il PDF firmato del documento gestionale.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento gestionale.","schema":{"type":"string","example":"attachment; filename=\"documento_gestionale_0012-0001.pdf\""}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"409":{"description":"Cassa chiusa","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Nessun Journal aperto disponibile"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Nessun Journal aperto disponibile"}}}}}}},"tags":["Funzioni fiscali - Documenti gestionali"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/gestionali\/chiusura\/{journalId}":{"post":{"summary":"Documento gestionale di chiusura","operationId":"documentoGestionaleDiChiusura","description":"Emette il Documento Gestionale PDF firmato della giornata fiscale chiusa.\nI totali provengono dal PEL, unica fonte fiscale. Come per il report vendite\nogni richiesta emette un nuovo documento, numerato sul journal corrente; le\ncopie gi\u00e0 emesse restano scaricabili dall'archivio gestionali.","parameters":[],"responses":{"200":{"description":"Il PDF firmato del documento gestionale.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento gestionale.","schema":{"type":"string","example":"attachment; filename=\"documento_gestionale_0012-0001.pdf\""}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"409":{"description":"Corrispettivi non trasmessi","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Chiusura non ancora trasmessa all'AdE"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Chiusura non ancora trasmessa all'AdE"}}}}}}},"tags":["Funzioni fiscali - Documenti gestionali"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}},{"in":"path","name":"journalId","description":"L'id della chiusura (campo `id` dello storico chiusure).","example":12,"required":true,"schema":{"type":"integer"}}]},"\/api\/pem\/{serial_number}\/fiscale\/emergenza\/chiusura":{"post":{"summary":"Chiusura di emergenza","operationId":"chiusuraDiEmergenza","description":"Trasmette al PEL gli aggregati della giornata annotati sul registro di\nemergenza dei corrispettivi: riepiloghi IVA e totali dei pagamenti,\ndichiarati dall'esercente. Ammessa solo a PEM `Fuori servizio`; la\nchiusura riguarda la giornata in cui \u00e8 inviata.\n\nUna giornata ammette pi\u00f9 chiusure, anche con dati diversi: ogni\n`idempotency_key` (UUID scelto dal client) \u00e8 una chiusura e un invio\ndistinto al PEL. Ripetere la chiamata con la stessa chiave \u00e8 sicuro: se\nla chiusura \u00e8 gi\u00e0 trasmessa si riceve il suo esito senza un nuovo invio,\nse l'invio era fallito lo si ritenta. La stessa chiave con dati diversi,\no gi\u00e0 usata su un altro PEM, \u00e8 rifiutata (422).","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"dati":{"id_presa_in_carico":"12345","n_doc_commerciali":12}},"properties":{"success":{"type":"boolean","example":true},"dati":{"type":"object","properties":{"id_presa_in_carico":{"type":"string","example":"12345"},"n_doc_commerciali":{"type":"integer","example":12}}}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"description":"","content":{"application\/json":{"schema":{"oneOf":[{"description":"Chiave gi\u00e0 usata con dati diversi","type":"object","example":{"success":false,"message":"La chiave \u00e8 gi\u00e0 stata usata per una chiusura di emergenza con dati diversi: usane una nuova.","errors":{"idempotency_key":["La chiave \u00e8 gi\u00e0 stata usata per una chiusura di emergenza con dati diversi: usane una nuova."]}},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"La chiave \u00e8 gi\u00e0 stata usata per una chiusura di emergenza con dati diversi: usane una nuova."},"errors":{"type":"object","properties":{"idempotency_key":{"type":"array","example":["La chiave \u00e8 gi\u00e0 stata usata per una chiusura di emergenza con dati diversi: usane una nuova."],"items":{"type":"string"}}}}}},{"description":"Validazione fallita","type":"object","example":{"success":false,"message":"L'imposta non \u00e8 coerente con imponibile e aliquota (attesa 22.00).","errors":{"riepiloghi.0.imposta":["L'imposta non \u00e8 coerente con imponibile e aliquota (attesa 22.00)."]}},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"L'imposta non \u00e8 coerente con imponibile e aliquota (attesa 22.00)."},"errors":{"type":"object","properties":{"riepiloghi.0.imposta":{"type":"array","example":["L'imposta non \u00e8 coerente con imponibile e aliquota (attesa 22.00)."],"items":{"type":"string"}}}}}}]}}}}},"tags":["Funzioni fiscali - Emergenza"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"idempotency_key":{"type":"string","description":"UUID scelto dal client, uno per chiusura e propagato al PEL. Ripetendo la chiamata con la stessa chiave non si crea una seconda chiusura: si riceve l'esito di quella gi\u00e0 trasmessa, o si ritenta l'invio fallito. La stessa chiave con dati diversi, o gi\u00e0 usata su un altro PEM, \u00e8 rifiutata (422). Deve essere un UUID valido.","example":"3f1c2a9e-8b7d-4c1e-9a2f-5d6e7f8a9b0c"},"n_doc_commerciali":{"type":"integer","description":"Numero di documenti commerciali annotati sul registro di emergenza nella giornata. Almeno 1. Al massimo 999999999.","example":12},"riepiloghi":{"type":"array","description":"","items":{"type":"object","properties":{"iva":{"type":"string","description":"Aliquota IVA (4, 5, 10, 22). Richiede `imposta`.","example":"22","nullable":true},"natura":{"type":"string","description":"Codice natura (N1\u2013N6), in alternativa a `iva`.","enum":["N1","N2","N3","N4","N5","N6"],"nullable":true},"ventilazione_iva":{"type":"string","description":"Ventilazione IVA (`SI`), in alternativa a `iva` e `natura`.","enum":["SI"],"nullable":true},"importo_parziale":{"type":"string","description":"Imponibile della riga, stringa decimale con al massimo 2 decimali (pu\u00f2 essere negativo). Al netto dell'IVA (al lordo con `ventilazione_iva`), al netto di resi, annulli, beni in sospeso e non riscossi, ma comprensivo degli omaggi. Formato: <code>\/^-?\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","example":"100.00"},"imposta":{"type":"string","description":"Imposta della riga: obbligatoria se e solo se \u00e8 indicata `iva`, coerente con `importo_parziale \u00d7 aliquota` entro \u00b10,01. Formato: <code>\/^-?\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","example":"22.00","nullable":true},"codice_attivita":{"type":"string","description":"Codice Ateco della riga (facoltativo), tra quelli configurati sul PEM.","enum":[null],"nullable":true},"totale_ammontare_resi":{"type":"string","description":"Ammontare dei resi (facoltativo, \u2265 0, al netto dell'IVA; al lordo con ventilazione IVA). Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","nullable":true},"totale_ammontare_annulli":{"type":"string","description":"Ammontare degli annulli (facoltativo, \u2265 0). Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","nullable":true},"beni_in_sospeso":{"type":"string","description":"Beni in sospeso (facoltativo, \u2265 0). Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","nullable":true},"non_riscosso_servizi":{"type":"string","description":"Non riscosso servizi (facoltativo, \u2265 0). Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","nullable":true},"non_riscosso_fatture":{"type":"string","description":"Non riscosso fatture (facoltativo, \u2265 0). Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","nullable":true},"non_riscosso_dcra_ssn":{"type":"string","description":"Non riscosso DCR a SSN (facoltativo, \u2265 0). Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","nullable":true},"non_riscosso_omaggio":{"type":"string","description":"Non riscosso omaggio (facoltativo, \u2265 0). Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","nullable":true}},"required":["importo_parziale"]}},"totali":{"type":"object","description":"","properties":{"pagato_contanti":{"type":"string","description":"Totale pagato in contanti. Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","example":"100.00"},"pagato_elettronico":{"type":"string","description":"Totale pagato con strumenti elettronici. Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","example":"77.55"},"sconto_a_pagare":{"type":"string","description":"Totale degli sconti a pagare. Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>.","example":"0.00"},"ticket":{"type":"object","description":"Buoni pasto incassati (facoltativo). Senza opzione buoni pasto sono un normale pagamento. Con l'opzione attiva nella giornata richiedono un riepilogo al 10% il cui lordo (`(importo_parziale + non_riscosso_servizi) \u00d7 1,10`) li copra, e il sistema attribuisce il riferimento normativo `TICKET` ai riepiloghi al 10%: il client non invia `rif_normativo`.","properties":{"pagato_ticket":{"type":"string","description":"Importo pagato con buoni pasto. Obbligatorio se \u00e8 presente <code>totali.ticket<\/code>. Formato: <code>\/^\\d{1,11}(\\.\\d{1,2})?$\/<\/code>."},"numero_ticket":{"type":"integer","description":"Numero di buoni pasto (\u2265 1). Obbligatorio se \u00e8 presente <code>totali.ticket<\/code>. Almeno 1. Al massimo 999999999."}},"nullable":true}},"required":["pagato_contanti","pagato_elettronico","sconto_a_pagare"]}},"required":["idempotency_key","n_doc_commerciali","riepiloghi","totali"],"example":{"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"}}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/opzione-buoni-pasto":{"get":{"summary":"Stato opzione buoni pasto","operationId":"statoOpzioneBuoniPasto","description":"Restituisce lo stato *efficace* dell'opzione (quello che governa\nl'emissione) e, se una scelta \u00e8 stata registrata ma decorre dal primo\ngiorno del mese successivo (\u00a75.3), anche la scelta in sospeso.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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},"properties":{"success":{"type":"boolean","example":true},"attiva":{"type":"boolean","example":true},"opzione":{"type":"object","properties":{"attiva":{"type":"boolean","example":true},"aggiornato_il":{"type":"string","example":"12-08-2026 10:00:00"},"decorre_dal":{"type":"string","example":"12-08-2026 10:00:00"}}},"scelta_pendente":{"type":"string","example":null,"nullable":true},"modificabile":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Funzioni fiscali - Opzione buoni pasto"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"post":{"summary":"Attiva\/disattiva opzione buoni pasto","operationId":"attivadisattivaOpzioneBuoniPasto","description":"Registra l'attivazione o disattivazione dell'opzione per il trattamento dei\nbuoni pasto (ST v1.4 \u00a75.3). Ammessa solo a cassa chiusa. Ha effetto dal\nmomento della scelta, salvo che nel mese corrente sia gi\u00e0 stato emesso\nalmeno un DC con buoni pasto accettati: in tal caso decorre dal primo\ngiorno del mese successivo (campo `decorre_dal` della risposta).","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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"}},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Opzione buoni pasto aggiornata"},"opzione":{"type":"object","properties":{"attiva":{"type":"boolean","example":true},"aggiornato_il":{"type":"string","example":"12-08-2026 10:00:00"},"decorre_dal":{"type":"string","example":"01-09-2026 00:00:00"}}}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"description":"Ruolo non ammesso","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"description":"Cassa aperta","content":{"application\/json":{"schema":{"type":"object","example":{"error_code":"BP001","message":"Impossibile modificare opzione buoni pasto. Effettua chiusura di cassa e riprova."},"properties":{"error_code":{"type":"string","example":"BP001"},"message":{"type":"string","example":"Impossibile modificare opzione buoni pasto. Effettua chiusura di cassa e riprova."}}}}}}},"tags":["Funzioni fiscali - Opzione buoni pasto"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"attiva":{"type":"boolean","description":"true per attivare l'opzione di trattamento dei buoni pasto, false per disattivarla. Il cambio \u00e8 ammesso solo a cassa chiusa.","example":true}},"required":["attiva"],"example":{"attiva":true}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/opzione-buoni-pasto\/storico":{"get":{"summary":"Storico opzione buoni pasto","operationId":"storicoOpzioneBuoniPasto","description":"Restituisce lo storico delle attivazioni\/disattivazioni dell'opzione,\ncome richiesto dalle ST v1.4 (\u00a73.4.2, lettura e stampa).","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"storico":[{"attiva":true,"aggiornato_il":"12-08-2026 10:00:00","utente":"Mario Rossi"}]},"properties":{"success":{"type":"boolean","example":true},"storico":{"type":"array","example":[{"attiva":true,"aggiornato_il":"12-08-2026 10:00:00","utente":"Mario Rossi"}],"items":{"type":"object","properties":{"attiva":{"type":"boolean","example":true},"aggiornato_il":{"type":"string","example":"12-08-2026 10:00:00"},"utente":{"type":"string","example":"Mario Rossi"}}}}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Funzioni fiscali - Opzione buoni pasto"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/richieste":{"get":{"summary":"Lista richieste","operationId":"listaRichieste","description":"Recupera la lista delle richieste effettuate dal PEM specificato.","parameters":[{"in":"query","name":"tipo","description":"Filtra per tipo di richiesta (CENSIMENTO, CORRISPETTIVI).","example":"CENSIMENTO","required":false,"schema":{"type":"string","description":"Filtra per tipo di richiesta (CENSIMENTO, CORRISPETTIVI).","example":"CENSIMENTO","enum":["CENSIMENTO","CORRISPETTIVI"]}}],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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"}]},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Richieste PEM recuperate"},"richieste":{"type":"array","example":[{"id":1,"id_presa_in_carico":"ABC123","stato":"PRONTA","data":"2025-07-01 10:30:00","tipo":"CENSIMENTO"}],"items":{"type":"object","properties":{"id":{"type":"integer","example":1},"id_presa_in_carico":{"type":"string","example":"ABC123"},"stato":{"type":"string","example":"PRONTA"},"data":{"type":"string","example":"2025-07-01 10:30:00"},"tipo":{"type":"string","example":"CENSIMENTO"}}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"}},"tags":["Funzioni fiscali - Richieste PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/richieste\/stato\/{idRichiesta}":{"get":{"summary":"Verifica stato richiesta","operationId":"verificaStatoRichiesta","description":"Controlla lo stato attuale di una richiesta PEM specifica.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"Stato richiesta: COMPLETED","stato":"COMPLETED"},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Stato richiesta: COMPLETED"},"stato":{"type":"string","example":"COMPLETED"}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Funzioni fiscali - Richieste PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}},{"in":"path","name":"idRichiesta","description":"L'id della richiesta (campo `id` della lista).","example":1,"required":true,"schema":{"type":"integer"}}]},"\/api\/pem\/{serial_number}\/fiscale\/richieste\/esito\/{idRichiesta}":{"get":{"summary":"Recupera esito richiesta","operationId":"recuperaEsitoRichiesta","description":"Recupera l'esito finale di una richiesta pronta.\nSe l'esito \u00e8 gi\u00e0 presente nel database, lo restituisce direttamente\nsenza effettuare una nuova chiamata al PEL.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"Esito richiesta recuperato","esito":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Esito richiesta recuperato"},"esito":{"type":"string","example":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Funzioni fiscali - Richieste PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}},{"in":"path","name":"idRichiesta","description":"L'id della richiesta (campo `id` della lista).","example":1,"required":true,"schema":{"type":"integer"}}]},"\/api\/pem\/{serial_number}\/fiscale\/segnalazioni\/inattivita":{"get":{"summary":"Periodi di inattivit\u00e0","operationId":"periodiDiInattivit","description":"Elenca i periodi di inattivit\u00e0 segnalati per il PEM, dal pi\u00f9 recente, con\nlo stato dell'inoltro al PEL.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"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"}]},"properties":{"status":{"type":"string","example":"success"},"data":{"type":"array","example":[{"id":3,"serial_number":"ASVS-241232","dal":"2026-12-24 00:00:00","al":"2027-01-06 23:59:59","stato":"PENDING"}],"items":{"type":"object","properties":{"id":{"type":"integer","example":3},"serial_number":{"type":"string","example":"ASVS-241232"},"dal":{"type":"string","example":"2026-12-24 00:00:00"},"al":{"type":"string","example":"2027-01-06 23:59:59"},"stato":{"type":"string","example":"PENDING"}}}}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Funzioni fiscali - Segnalazioni"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"post":{"summary":"Segnala un periodo di inattivit\u00e0","operationId":"segnalaUnPeriodoDiInattivit","description":"Comunica all'AdE, tramite il PEL, un periodo futuro in cui il PEM non\nemetter\u00e0 documenti (ferie, chiusura stagionale). La segnalazione \u00e8\naccodata e inoltrata in modo asincrono: la risposta \u00e8 202. Le date sono\nnel formato `Y-m-d H:i:s`, `al` successiva a `dal` e nel futuro.","parameters":[],"responses":{"202":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"status":"success","message":"Periodo inattivo registrato"},"properties":{"status":{"type":"string","example":"success"},"message":{"type":"string","example":"Periodo inattivo registrato"}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"}},"tags":["Funzioni fiscali - Segnalazioni"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"dal":{"type":"string","description":"Data nel formato <code>Y-m-d H:i:s<\/code>.","example":"2026-11-01 00:00:00"},"al":{"type":"string","description":"Data nel formato <code>Y-m-d H:i:s<\/code>. Deve essere una data successiva a <code>dal<\/code>.","example":"2026-11-30 23:59:59"}},"required":["dal","al"],"example":{"dal":"2026-11-01 00:00:00","al":"2026-11-30 23:59:59"}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/stati":{"get":{"summary":"Lista Stati PEM","operationId":"listaStatiPEM","description":"Restituisce la lista degli stati del PEM corrente.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"data":[{"id":1,"stato":"In servizio"},{"id":2,"stato":"Dismesso"}]},"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","example":[{"id":1,"stato":"In servizio"},{"id":2,"stato":"Dismesso"}],"items":{"type":"object","properties":{"id":{"type":"integer","example":1},"stato":{"type":"string","example":"In servizio"}}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"}},"tags":["Funzioni fiscali - Stato PEM"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:read"]},"security":[{"oauth2":["fiscale:read"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/stato":{"put":{"summary":"Modifica lo stato del PEM","operationId":"modificaLoStatoDelPEM","description":"Comunica al PEL il cambio di stato del PEM.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"Stato PEM aggiornato con successo","data":{"id":1,"stato":"In servizio"}},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Stato PEM aggiornato con successo"},"data":{"type":"object","properties":{"id":{"type":"integer","example":1},"stato":{"type":"string","example":"In servizio"}}}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"description":"Validazione fallita","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"La motivazione \u00e8 obbligatoria","errors":{"motivazione":["Il campo motivazione \u00e8 obbligatorio"]}},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"La motivazione \u00e8 obbligatoria"},"errors":{"type":"object","properties":{"motivazione":{"type":"array","example":["Il campo motivazione \u00e8 obbligatorio"],"items":{"type":"string"}}}}}}}}}},"tags":["Funzioni fiscali - Stato PEM"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"stato":{"type":"string","description":"Stato del PEM (01: Fuori servizio, 03: In servizio). La dismissione (02) deve usare endpoint dedicato. Formato: <code>\/^\\d{2}$\/D<\/code>.","example":"01","enum":["01","03"]},"motivazione":{"type":"string","description":"Motivazione del Fuori servizio (01), obbligatoria con quello stato (01: Problemi hardware PEM, 02: Problemi software PEM, 03: Problemi di comunicazione PEM-PEL, 08: Mancata integrit\u00e0, 09: Messa in magazzino - periodo di inattivit\u00e0, 10: Altro). Da non inviare con stato In servizio (03): il sistema trasmette 06 (Inizio ciclo di vita PEM) al primo passaggio in servizio e 07 (Ripristino da un fuori servizio) altrimenti. Formato: <code>\/^\\d{2}$\/D<\/code>.","example":"01","enum":["01","02","03","08","09","10"],"nullable":true},"note":{"type":"string","description":"Note sul cambiamento di stato, obbligatorie con stato Fuori servizio (01) qualunque sia la motivazione (AdE rifiuta altrimenti con CS009); facoltative con stato In servizio (03). Massimo 255 caratteri. Al massimo 255 caratteri.","example":"Guasto alla rete del punto vendita","nullable":true}},"required":["stato"],"example":{"stato":"01","motivazione":"01","note":"Guasto alla rete del punto vendita"}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/stato\/dismissione":{"post":{"summary":"Dismissione del PEM","operationId":"dismissioneDelPEM","description":"Porta il PEM nello stato definitivo *Dismesso* e lo comunica al PEL. Riservata\nall'esercente titolare; lo stato e la motivazione non si scelgono (campi rifiutati).","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"Dismissione PEM completata con successo","data":{"id":7,"stato":"Dismesso"}},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Dismissione PEM completata con successo"},"data":{"type":"object","properties":{"id":{"type":"integer","example":7},"stato":{"type":"string","example":"Dismesso"}}}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"}},"tags":["Funzioni fiscali - Stato PEM"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Note sulla dismissione del PEM, obbligatorie (AdE rifiuta altrimenti con CS009). Massimo 255 caratteri. Al massimo 255 caratteri.","example":"Chiusura definitiva del ciclo di vita PEM"}},"required":["note"],"example":{"note":"Chiusura definitiva del ciclo di vita PEM"}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/invio\/dc":{"post":{"summary":"Invio DC","operationId":"invioDC","description":"Emette un documento commerciale di vendita: genera e firma l'XML, lo aggiunge\nal Journal e ne accoda la trasmissione al PEL (la risposta non attende il PEL).\nAmmesso solo su un PEM In servizio.\n\n`idempotency_key` (UUID) rende sicuro ripetere la chiamata: con una chiave gi\u00e0\nusata sul PEM la risposta \u00e8 il documento gi\u00e0 emesso, senza emetterne un altro.\nCome richiesto dalle specifiche AdE, l'unico output \u00e8 lo stream di byte del PDF\nfirmato (PAdES, `application\/pdf`): il testo ESC\/POS per la stampante termica \u00e8\nnei metadati XMP del PDF (`billy:escPosBase64`) e `Content-Location` \u00e8 l'URL\npubblico dello stesso PDF (con `?regalo=1` la copia di cortesia). Gli errori\nrestano JSON. Il primo DC dopo una chiusura apre la nuova giornata.","parameters":[],"responses":{"200":{"description":"Il PDF firmato (PAdES) del documento emesso.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento (NNNN-PPPP).","schema":{"type":"string","example":"inline; filename=\"DC_0012-0007.pdf\""}},"Content-Location":{"description":"L'URL pubblico dello stesso PDF, senza token: con `?regalo=1` la copia di cortesia (solo DC di vendita). Il segmento prima di \/pdf \u00e8 l'hash del documento, URL-encoded.","schema":{"type":"string","example":"https:\/\/pem-staging.billyssw.it\/pem\/ASVS-241232\/fiscale\/consultazione\/dc\/YjQ0ZDJmMGE5YzFl...MmEzYjQ%3D\/pdf"}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"409":{"description":"Giornata aperta da pi\u00f9 di 24 ore","content":{"application\/json":{"schema":{"type":"object","example":{"error_code":"JN002","message":"Apertura effettuata da pi\u00f9 di 24 ore (ID: 42, Data: 2026-10-07 08:00:00)"},"properties":{"error_code":{"type":"string","example":"JN002"},"message":{"type":"string","example":"Apertura effettuata da pi\u00f9 di 24 ore (ID: 42, Data: 2026-10-07 08:00:00)"}}}}}},"422":{"description":"Validazione fallita","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"La somma degli importi dei pagamenti \u00e8 inferiore al totale da pagare","errors":{"pagamenti":["La somma degli importi dei pagamenti \u00e8 inferiore al totale da pagare"]}},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"La somma degli importi dei pagamenti \u00e8 inferiore al totale da pagare"},"errors":{"type":"object","properties":{"pagamenti":{"type":"array","example":["La somma degli importi dei pagamenti \u00e8 inferiore al totale da pagare"],"items":{"type":"string"}}}}}}}}},"502":{"$ref":"#\/components\/responses\/AperturaGiornataNonRiuscita"}},"tags":["Funzioni fiscali - Trasmissioni"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"idempotency_key":{"type":"string","description":"UUID scelto dal client, uno per documento: ripetendo la chiamata con la stessa chiave si riceve il documento gi\u00e0 emesso. Deve essere un UUID valido. Al massimo 36 caratteri.","example":"3f1c2a9e-8b7d-4c1e-9a2f-5d6e7f8a9b0c"},"sconto_a_pagare":{"type":"number","description":"Lo sconto a pagare sul documento commerciale.","example":2,"nullable":true},"arrotondamento_dl50_difetto":{"type":"boolean","description":"Indica che lo sconto a pagare rappresenta l'arrotondamento DL 50\/2017 per difetto. Ammesso solo con pagamento integralmente in contanti e importo massimo 0,02 euro.","example":false,"nullable":true},"arrotondamento_dl50_eccesso":{"type":"number","description":"Importo dell'arrotondamento DL 50\/2017 per eccesso. Ammesso solo con pagamento integralmente in contanti, mutuamente esclusivo con arrotondamento_dl50_difetto e importo massimo 0,02 euro. Almeno 0.","example":0.01,"nullable":true},"sconto_subtotale":{"type":"number","description":"Sconto applicato all'intero subtotale (importo assoluto in euro, dopo gli sconti di linea). Viene ripartito sulle singole linee ai soli fini fiscali e non pu\u00f2 superare il subtotale al netto degli sconti di linea. Almeno 0.","example":1.8,"nullable":true},"codice_lotteria":{"type":"string","description":"Codice lotteria del cliente (massimo 8 caratteri). Richiede un totale di almeno 1 euro pagato con un unico pagamento PP; alternativo a cessionario_committente. Al massimo 8 caratteri.","example":"ABC12345","nullable":true},"cessionario_committente":{"type":"string","description":"Codice fiscale del cliente (massimo 16 caratteri), per il documento commerciale con codice fiscale. Alternativo a codice_lotteria. Al massimo 16 caratteri.","example":"RSSMRA85M01H501Z","nullable":true},"ateco":{"type":"string","description":"Codice ATECO dell'operazione (massimo 6 caratteri). Oggi \u00e8 accettato ma non riportato nel documento. Al massimo 6 caratteri.","example":"561011","nullable":true},"appendice":{"type":"array","description":"Una riga di appendice (massimo 255 caratteri). Al massimo 255 caratteri.","example":["Grazie e arrivederci"],"items":{"type":"string"}},"elementi":{"type":"array","description":"Le righe (elementi contabili) del documento commerciale, al massimo 200 e con al massimo 40 aliquote distinte. Al massimo 200 elementi.","items":{"type":"object","properties":{"descrizione":{"type":"string","description":"La descrizione dell'elemento. Al massimo 255 caratteri.","example":"Caff\u00e8 espresso"},"bene_servizio":{"type":"string","description":"Indica se l'elemento \u00e8 un bene (B) o un servizio (S).","example":"B","enum":["B","S"]},"quantita":{"type":"number","description":"La quantit\u00e0 dell'elemento (due decimali). Almeno 0.","example":"2"},"prezzo_unitario":{"type":"number","description":"Il prezzo unitario dell'elemento, IVA inclusa, in euro (due decimali). Almeno 0.","example":"1.20"},"iva":{"type":"string","description":"Aliquota IVA (4, 5, 10, 22), natura dell'operazione (N1-N6) o VI per la ventilazione.","example":"10","enum":["4","5","10","22","N1","N2","N3","N4","N5","N6","VI"]},"sconto":{"type":"number","description":"Sconto sulla riga, importo assoluto in euro. Almeno 0.","example":0.2,"nullable":true},"maggiorazione":{"type":"number","description":"La maggiorazione applicata all'elemento come importo assoluto. Almeno 0.","example":1.5,"nullable":true},"acconto_versato_beni_non_consegnati":{"type":"boolean","description":"Indica se l'elemento \u00e8 un acconto versato per beni non consegnati.","example":false,"nullable":true},"omaggio":{"type":"boolean","description":"Indica se l'elemento \u00e8 un omaggio.","example":false,"nullable":true},"id_reparto":{"type":"integer","description":"L'ID del reparto associato all'elemento.","example":1,"nullable":true}},"required":["descrizione","bene_servizio","quantita","prezzo_unitario","iva"]}},"pagamenti":{"type":"array","description":"I pagamenti. Obbligatori se il totale da pagare \u00e8 maggiore di zero; devono coprirlo (i contanti possono eccederlo: la differenza \u00e8 il resto).","items":{"type":"object","properties":{"importo":{"type":"number","description":"L'importo del pagamento in euro. Almeno 0.","example":"2.40"},"metodo":{"type":"string","description":"PC contanti, PP elettronico, TK buoni pasto (con l'opzione buoni pasto attiva solo su operazioni al 10%), NRF\/NRB\/NRS\/NRD non riscosso (fattura, beni, servizi, DCR a SSN). NRF e NRD escludono altri pagamenti.","example":"PC","enum":["PC","PP","TK","NRF","NRB","NRS","NRD"]},"numero_ticket":{"type":"integer","description":"Il numero del ticket per i pagamenti con metodo TK. Obbligatorio se <code>pagamenti.*.metodo<\/code> vale <code>TK<\/code>. Almeno 0.","example":123456},"pos":{"type":"object","description":"Facoltativo, per i pagamenti PP: dati della transazione sul terminale.","properties":{"pos":{"type":"string","description":"Circuito o fornitore del terminale (massimo 32 caratteri). Obbligatorio se \u00e8 presente <code>pagamenti.*.pos<\/code>.","example":"Nexi"},"uuid":{"type":"string","description":"Identificativo univoco della transazione. Obbligatorio se \u00e8 presente <code>pagamenti.*.pos<\/code>. Al massimo 50 caratteri.","example":"9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f"},"data_ora":{"type":"string","description":"Data e ora della transazione. Obbligatorio se \u00e8 presente <code>pagamenti.*.pos<\/code>. Deve essere una data valida.","example":"2026-10-08T10:15:00+02:00"},"tid":{"type":"string","description":"Terminal ID. Al massimo 36 caratteri.","example":"12345678","nullable":true},"auth_code":{"type":"string","description":"Codice di autorizzazione (massimo 20 caratteri). Al massimo 255 caratteri.","example":"A1B2C3","nullable":true}}}},"required":["importo","metodo"]}}},"required":["idempotency_key","elementi"],"example":{"idempotency_key":"3f1c2a9e-8b7d-4c1e-9a2f-5d6e7f8a9b0c","elementi":[{"descrizione":"Caff\u00e8 espresso","bene_servizio":"B","quantita":"2","prezzo_unitario":"1.20","iva":"10"}],"pagamenti":[{"metodo":"PC","importo":"2.40"}]}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/invio\/annullo":{"post":{"summary":"Annulla DC","operationId":"annullaDC","description":"Emette il documento commerciale di annullo di una vendita e ne accoda la\ntrasmissione al PEL. Per una vendita dello stesso PEM basta il suo\n`progressivo` (`NNNN-PPPP`): righe e codice lotteria si prendono dall'originale.\nPer un documento di un altro dispositivo si indicano `matricola_annullo`,\n`progressivo`, `dataOra` ed `elementi`; con matricola `POS`, `VR` o `ND` il\nprogressivo non serve. La risposta, come per *Invio DC*, \u00e8 il PDF firmato del documento.","parameters":[],"responses":{"200":{"description":"Il PDF firmato (PAdES) del documento emesso.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento (NNNN-PPPP).","schema":{"type":"string","example":"inline; filename=\"DC_0012-0007.pdf\""}},"Content-Location":{"description":"L'URL pubblico dello stesso PDF, senza token: con `?regalo=1` la copia di cortesia (solo DC di vendita). Il segmento prima di \/pdf \u00e8 l'hash del documento, URL-encoded.","schema":{"type":"string","example":"https:\/\/pem-staging.billyssw.it\/pem\/ASVS-241232\/fiscale\/consultazione\/dc\/YjQ0ZDJmMGE5YzFl...MmEzYjQ%3D\/pdf"}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"description":"Documento inesistente","content":{"application\/json":{"schema":{"type":"object","example":{"error_code":"DC001","message":"Documento commerciale non trovato"},"properties":{"error_code":{"type":"string","example":"DC001"},"message":{"type":"string","example":"Documento commerciale non trovato"}}}}}},"409":{"description":"Gi\u00e0 annullato","content":{"application\/json":{"schema":{"type":"object","example":{"error_code":"DC003","message":"Il documento commerciale \u00e8 gi\u00e0 stato annullato"},"properties":{"error_code":{"type":"string","example":"DC003"},"message":{"type":"string","example":"Il documento commerciale \u00e8 gi\u00e0 stato annullato"}}}}}},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"},"502":{"$ref":"#\/components\/responses\/AperturaGiornataNonRiuscita"}},"tags":["Funzioni fiscali - Trasmissioni"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"idempotency_key":{"type":"string","description":"Chiave UUID usata per rendere idempotente la richiesta di annullo. Deve essere un UUID valido. Al massimo 36 caratteri.","example":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"},"progressivo":{"type":"string","description":"Il progressivo (NNNN-PPPP) del documento da annullare. Obbligatorio salvo matricola_annullo POS, VR o ND. Al massimo 11 caratteri.","example":"0012-0007"},"matricola_annullo":{"type":"string","description":"Solo per un documento emesso da un altro dispositivo: la sua matricola, oppure POS, VR o ND. Vuoto per un documento di questo PEM. Al massimo 11 caratteri.","example":"99MEX012345"},"dataOra":{"type":"string","description":"Data e ora del documento da annullare. Obbligatoria con matricola_annullo. Deve essere una data valida.","example":"2026-01-15 18:30:00"},"codice_lotteria":{"type":"string","description":"Codice lotteria associato al documento. Questo campo \u00e8 opzionale e va fornito se il documento da annullare \u00e8 stato emesso da un altro dispositivo. Al massimo 8 caratteri.","example":"ABC12345","nullable":true},"elementi":{"type":"array","description":"L'array di elementi del documento di annullo. Questo campo \u00e8 obbligatorio se il documento da annullare \u00e8 stato emesso da un altro dispositivo.","items":{"type":"object","properties":{"descrizione":{"type":"string","description":"La descrizione dell'elemento. Al massimo 255 caratteri.","example":"Prodotto A"},"bene_servizio":{"type":"string","description":"Indica se l'elemento \u00e8 un bene (B) o un servizio (S).","example":"B","enum":["B","S"]},"quantita":{"type":"number","description":"La quantit\u00e0 dell'elemento.","example":2},"prezzo_unitario":{"type":"number","description":"Il prezzo unitario dell'elemento.","example":100},"iva":{"type":"string","description":"Il codice IVA applicato all'elemento. Obbligatorio se manca <code>elementi.*.id<\/code>.","enum":["4","5","10","22","N1","N2","N3","N4","N5","N6","VI"]},"sconto":{"type":"number","description":"Lo sconto applicato all'elemento.","example":10,"nullable":true},"acconto_versato_beni_non_consegnati":{"type":"boolean","description":"Indica se l'elemento \u00e8 un acconto versato per beni non consegnati.","example":false,"nullable":true},"omaggio":{"type":"boolean","description":"Indica se l'elemento \u00e8 un omaggio.","example":false,"nullable":true},"ateco":{"type":"string","description":"Al massimo 6 caratteri.","example":"bngz","nullable":true}},"required":["descrizione","bene_servizio","quantita","prezzo_unitario"]}}},"required":["idempotency_key"],"example":{"idempotency_key":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","progressivo":"0012-0007"}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/invio\/reso":{"get":{"summary":"Recupera dati reso DC","operationId":"recuperaDatiResoDC","description":"Restituisce le righe di un documento commerciale, con il loro `id` e la\nquantit\u00e0 gi\u00e0 resa (`reso`), per comporre la richiesta di reso.","parameters":[{"in":"query","name":"hash","description":"L'hash del documento commerciale (campo `hash` della risposta di emissione).","example":"YjQ0ZDJmMGE5YzFlNGI3ZDhmMDAxMmFiMzRjZDU2ZWY3ODkwYTFiMmMzZDRlNWY2YTdiOGM5ZDBlMWYyYTNiNA==","required":true,"schema":{"type":"string","description":"L'hash del documento commerciale (campo `hash` della risposta di emissione).","example":"YjQ0ZDJmMGE5YzFlNGI3ZDhmMDAxMmFiMzRjZDU2ZWY3ODkwYTFiMmMzZDRlNWY2YTdiOGM5ZDBlMWYyYTNiNA=="}}],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"dati":{"progressivo":"0012-0007","data":"2026-10-08 10:15:42","serial_number":"ASVS-241232","elementi_contabili":[{"id":5531,"descrizione":"Caff\u00e8 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}]}},"properties":{"success":{"type":"boolean","example":true},"dati":{"type":"object","properties":{"progressivo":{"type":"string","example":"0012-0007"},"data":{"type":"string","example":"2026-10-08 10:15:42"},"serial_number":{"type":"string","example":"ASVS-241232"},"elementi_contabili":{"type":"array","example":[{"id":5531,"descrizione":"Caff\u00e8 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}],"items":{"type":"object","properties":{"id":{"type":"integer","example":5531},"descrizione":{"type":"string","example":"Caff\u00e8 espresso"},"bene_servizio":{"type":"string","example":"B"},"quantita":{"type":"string","example":"2.00"},"prezzo_unitario":{"type":"string","example":"1.20"},"sconto":{"type":"string","example":"0.00"},"iva":{"type":"string","example":"10"},"acconto_versato_beni_non_consegnati":{"type":"boolean","example":false},"omaggio":{"type":"boolean","example":false},"reso":{"type":"integer","example":0}}}}}}}}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"description":"Documento inesistente","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Documento commerciale non trovato"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Documento commerciale non trovato"}}}}}}},"tags":["Funzioni fiscali - Trasmissioni"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"post":{"summary":"Reso DC","operationId":"resoDC","description":"Emette il documento commerciale di reso, totale o parziale, e ne accoda la\ntrasmissione al PEL. Per una vendita dello stesso PEM si indicano il suo\n`progressivo` e, per ogni riga resa, l'`id` della riga originale (da *Recupera\ndati reso DC*) con la `quantita`: il resto si prende dall'originale. Le righe di\nservizio non sono rendibili. Per un documento di un altro dispositivo si\nindicano `matricola_reso`, `progressivo`, `dataOra` e le righe complete.\nLa risposta, come per *Invio DC*, \u00e8 il PDF firmato del documento.","parameters":[],"responses":{"200":{"description":"Il PDF firmato (PAdES) del documento emesso.","headers":{"Content-Disposition":{"description":"Il nome del file contiene il progressivo del documento (NNNN-PPPP).","schema":{"type":"string","example":"inline; filename=\"DC_0012-0007.pdf\""}},"Content-Location":{"description":"L'URL pubblico dello stesso PDF, senza token: con `?regalo=1` la copia di cortesia (solo DC di vendita). Il segmento prima di \/pdf \u00e8 l'hash del documento, URL-encoded.","schema":{"type":"string","example":"https:\/\/pem-staging.billyssw.it\/pem\/ASVS-241232\/fiscale\/consultazione\/dc\/YjQ0ZDJmMGE5YzFl...MmEzYjQ%3D\/pdf"}}},"content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#\/components\/responses\/NonAutenticato"},"403":{"$ref":"#\/components\/responses\/NonAutorizzato"},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"409":{"description":"","content":{"application\/json":{"schema":{"oneOf":[{"description":"Quantit\u00e0 eccessiva","type":"object","example":{"error_code":"DC006","message":"Quantit\u00e0 reso maggiore di quantit\u00e0 rimanente"},"properties":{"error_code":{"type":"string","example":"DC006"},"message":{"type":"string","example":"Quantit\u00e0 reso maggiore di quantit\u00e0 rimanente"}}},{"description":"Riga di servizio","type":"object","example":{"error_code":"DC007","message":"Gli elementi marcati come Servizio non sono ammessi al reso"},"properties":{"error_code":{"type":"string","example":"DC007"},"message":{"type":"string","example":"Gli elementi marcati come Servizio non sono ammessi al reso"}}}]}}}},"422":{"$ref":"#\/components\/responses\/ValidazioneNonRiuscita"},"502":{"$ref":"#\/components\/responses\/AperturaGiornataNonRiuscita"}},"tags":["Funzioni fiscali - Trasmissioni"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"idempotency_key":{"type":"string","description":"Chiave UUID usata per rendere idempotente la richiesta di reso. Deve essere un UUID valido. Al massimo 36 caratteri.","example":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"},"progressivo":{"type":"string","description":"Il progressivo (NNNN-PPPP) del documento di vendita da rendere. Obbligatorio salvo matricola_reso POS, VR o ND. Al massimo 11 caratteri.","example":"0012-0007"},"matricola_reso":{"type":"string","description":"Solo per un documento emesso da un altro dispositivo: la sua matricola, oppure POS, VR o ND. Vuoto per un documento di questo PEM. Al massimo 11 caratteri.","example":"99MEX012345"},"dataOra":{"type":"string","description":"Data e ora del documento da rendere. Obbligatoria con matricola_reso. Deve essere una data valida.","example":"2026-01-15 18:30:00"},"codice_lotteria":{"type":"string","description":"Il codice lotteria associato al reso. Questo campo \u00e8 opzionale e va fornito se il documento di cui si vuole fare il reso \u00e8 stato emesso da un altro dispositivo. Al massimo 8 caratteri.","example":"ABC12345","nullable":true},"elementi":{"type":"array","description":"L'array di elementi contabili del documento commerciale.","items":{"type":"object","properties":{"quantita":{"type":"number","description":"La quantit\u00e0 dell'elemento da rendere.","example":"1"},"id":{"type":"integer","description":"L'id della riga originale da rendere (da Recupera dati reso DC). Obbligatorio se il documento \u00e8 stato emesso dallo stesso PEM.","example":5531},"descrizione":{"type":"string","description":"La descrizione dell'elemento. Questo campo \u00e8 obbligatorio se il documento di cui si vuole fare il reso \u00e8 stato emesso da un altro dispositivo. Al massimo 255 caratteri.","example":"Prodotto A"},"bene_servizio":{"type":"string","description":"Indica se l'elemento \u00e8 un bene (B). I servizi (S) non sono ammessi al reso. Questo campo \u00e8 obbligatorio se il documento di cui si vuole fare il reso \u00e8 stato emesso da un altro dispositivo.","example":"B","enum":["B"]},"prezzo_unitario":{"type":"number","description":"Il prezzo unitario dell'elemento da rendere. Questo campo \u00e8 obbligatorio se il documento di cui si vuole fare il reso \u00e8 stato emesso da un altro dispositivo.","example":10.5},"iva":{"type":"string","description":"Il codice IVA applicato all'elemento da rendere. Questo campo \u00e8 obbligatorio se il documento di cui si vuole fare il reso \u00e8 stato emesso da un altro dispositivo.","enum":["4","5","10","22","N1","N2","N3","N4","N5","N6","VI"]},"sconto":{"type":"number","description":"Lo sconto applicato all'elemento da rendere.","example":1,"nullable":true},"acconto_versato_beni_non_consegnati":{"type":"boolean","description":"Indica se l'elemento \u00e8 un acconto versato per beni non consegnati.","example":false,"nullable":true},"omaggio":{"type":"boolean","description":"Indica se l'elemento \u00e8 un omaggio.","example":false,"nullable":true},"ateco":{"type":"string","description":"Il codice ATECO associato all'elemento. Al massimo 6 caratteri.","example":"123456","nullable":true}},"required":["quantita"]}}},"required":["idempotency_key","elementi"],"example":{"idempotency_key":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","progressivo":"0012-0007","elementi":[{"id":5531,"quantita":"1"}]}}}}},"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/api\/pem\/{serial_number}\/fiscale\/invio\/chiusura":{"post":{"summary":"Chiusura giornaliera","operationId":"chiusuraGiornaliera","description":"Chiude la giornata fiscale: scrive il blocco di chiusura del Journal e accoda\nl'invio firmato al PEL, che trasmette i corrispettivi all'AdE. La risposta\narriva subito: l'esito si segue con *Storico chiusure* (`inviato_il`) e con le\nrichieste di tipo CORRISPETTIVI. Se ci sono DC appena emessi ancora in invio al\nPEL la risposta \u00e8 409 `JN005`: riprovare dopo qualche istante. Una giornata\naperta da 23 ore viene chiusa in automatico.","parameters":[],"responses":{"200":{"description":"success","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"message":"Chiusura in elaborazione"},"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Chiusura in elaborazione"}}}}}},"401":{"description":"Non autenticato","content":{"application\/json":{"schema":{"type":"object","example":{"message":"Non hai i permessi per accedere a questa risorsa.","error":"unauthenticated"},"properties":{"message":{"type":"string","example":"Non hai i permessi per accedere a questa risorsa."},"error":{"type":"string","example":"unauthenticated"}}}}}},"403":{"description":"Non autorizzato","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"message":"Richiesta non autorizzata"},"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Richiesta non autorizzata"}}}}}},"404":{"$ref":"#\/components\/responses\/PemNonTrovato"},"409":{"description":"","content":{"application\/json":{"schema":{"oneOf":[{"description":"DC ancora in invio","type":"object","example":{"error_code":"JN005","message":"Impossibile completare l'operazione: ci sono trasmissioni DC in attesa di invio"},"properties":{"error_code":{"type":"string","example":"JN005"},"message":{"type":"string","example":"Impossibile completare l'operazione: ci sono trasmissioni DC in attesa di invio"}}},{"description":"Gi\u00e0 chiusa","type":"object","example":{"error_code":"JN006","message":"Chiusura gi\u00e0 effettuata"},"properties":{"error_code":{"type":"string","example":"JN006"},"message":{"type":"string","example":"Chiusura gi\u00e0 effettuata"}}}]}}}}},"tags":["Funzioni fiscali - Trasmissioni"],"x-billy-accesso":{"tipo":"partner","scope":["fiscale:manage"]},"security":[{"oauth2":["fiscale:manage"]}]},"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","example":"ASVS-241232","required":true,"schema":{"type":"string"}}]},"\/pem\/{serial_number}\/fiscale\/consultazione\/dc\/{hash}\/pdf":{"get":{"summary":"PDF pubblico di un DC","description":"Il PDF firmato del documento, senza token: \u00e8 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.","tags":["Funzioni fiscali - Consultazione"],"x-billy-accesso":{"tipo":"pubblico"},"security":[],"parameters":[{"in":"path","name":"serial_number","description":"Il seriale del PEM.","required":true,"schema":{"type":"string","example":"ASVS-241232"}},{"in":"path","name":"hash","description":"L'hash del documento, URL-encoded.","required":true,"schema":{"type":"string","example":"YjQ0ZDJmMGE5YzFl...MmEzYjQ="}},{"in":"query","name":"width","description":"Larghezza in mm, da 58 a 120 (default 120); i valori fuori intervallo vengono riportati al limite.","required":false,"schema":{"type":"integer","example":58}},{"in":"query","name":"font_size","description":"Corpo del testo, da 6 a 14 (default 10), con lo stesso limite.","required":false,"schema":{"type":"integer","example":8}},{"in":"query","name":"regalo","description":"Con 1, la copia di cortesia senza importi (solo per i DC di vendita).","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Il PDF firmato del documento.","content":{"application\/pdf":{"schema":{"type":"string","format":"binary"}}}},"429":{"description":"Pi\u00f9 di 60 richieste al minuto dallo stesso indirizzo IP.","content":{"application\/json":{"example":{"message":"Too Many Attempts."}}}}}}}}}