Fatturazione
Fatturazione elettronica (FatturaPA) via provider esterno: i dati fiscali del cliente vivono sul record (account o contatto), il profilo emittente a livello di istanza, e da una trattativa si emette la fattura nel provider e se ne segue lo stato. L'uso operativo è descritto nella guida alla fatturazione.
| Metodo | Endpoint | Permesso | Cosa fa |
|---|---|---|---|
| GET | /api/billing/:module/:id | read sul modulo | Blocco fiscale del record. |
| PUT | /api/billing/:module/:id | update sul modulo | Salva il blocco fiscale. |
| GET | /api/billing/profile | admin | Profilo emittente (cedente/prestatore). |
| PUT | /api/billing/profile | admin | Salva il profilo emittente. |
| POST | /api/billing/test/:id | admin | Testa la connessione del provider di fatturazione (:id = connessione). |
| POST | /api/billing/deals/:id/invoice | update su deals | Emette la fattura della trattativa nel provider. |
| GET | /api/billing/deals/:id/invoice-status | read su deals | Stato live (pagamento + SDI) della fattura. |
| GET | /api/billing/invoices | read su deals | Le fatture emesse. |
01Dati fiscali del cliente
Il blocco fiscale (cessionario/committente) di un record. :module
può essere solo accounts o contacts
(altri moduli → 400 «Modulo non fatturabile»). La validazione
al salvataggio è lenient: normalizza e rifiuta solo i valori malformati
presenti, così puoi compilare il profilo progressivamente: il controllo «tutti i campi
obbligatori» avviene all'emissione.
| Campo | Tipo | Descrizione |
|---|---|---|
| tipo_soggetto | string | privato, azienda (default) o pa. |
| denominazione / nome + cognome | string | Ragione sociale (azienda/PA) oppure nome e cognome (privato). |
| partita_iva · codice_fiscale | string | Identificativi fiscali; id_paese ISO-2 (default IT). |
| codice_destinatario | string | Codice SDI a 7 caratteri, in alternativa a pec_destinatario. |
| codice_univoco_ufficio | string | Per la PA: codice ufficio a 6 caratteri. |
| sede | object | { indirizzo, numero_civico, cap, comune, provincia, nazione }: CAP numerico, provincia/nazione a 2 lettere. |
| metodo_pagamento | string | Codice modalità di pagamento FatturaPA (es. MP05). |
{ "success": true, "data": { "eInvoice": { "tipo_soggetto": "azienda", "denominazione": "ACME S.r.l.", … } } }
La GET sullo stesso path restituisce il blocco salvato
(eInvoice: null se non ancora compilato). Lo scope del record
vale come per le altre letture: un record fuori scope → 404.
02Emissione e stato
Compone la fattura dalla trattativa (le righe prodotti/servizi del deal + il blocco fiscale del cliente + il profilo emittente) e la crea nel provider di fatturazione configurato. È un'operazione create-only: la fattura NON viene inviata allo SDI da qui: l'invio si finalizza nel gestionale del provider. Se mancano dati fiscali obbligatori la risposta è 422 con l'elenco di cosa manca; una doppia emissione sullo stesso deal viene rifiutata.
Interroga il provider per lo stato corrente della fattura del deal: stato di pagamento e stato SDI (consegna al destinatario).
Il provider si configura come connessione (vedi
Connessioni) e si verifica con
POST /api/billing/test/:id. Le credenziali sono cifrate at-rest
come tutte le connessioni.