La fattura SDI viene rifiutata: cause comuni e fix

Sintomo

La chiamata a create-xml (o l’invio SdI collegato) restituisce un errore JSON invece dell’XML/esito atteso, oppure il documento viene respinto prima dell’invio.

Cause

• Regime fiscale non allineato — se sia il payload che l’account hanno tax_regime impostato, i due valori devono coincidere. Se non coincidono, la generazione fallisce.
• Nota di credito su piano free — i piani free non possono creare note di credito (type: credit_note).
• Nota di credito senza riferimento alla fattura collegata — le note di credito richiedono connected_invoice_data.id e connected_invoice_data.date valorizzati.
• Manca l’instradamento del destinatario — serve transmitter_data.sdi_code oppure transmitter_data.recipient_pec; senza uno dei due l’invio non può essere instradato.
• Payload incompleto — campi obbligatori mancanti nel payload condiviso (es. dati fornitore/cliente, totale documento, almeno una riga in order_items).

Fix

1. Controlla il tax_regime configurato sull’account (pannello POP) e allinealo a quello inviato nel payload, oppure ometti il campo nel payload se non necessario.
2. Se stai generando una nota di credito, verifica piano attivo e presenza di connected_invoice_data.id/date.
3. Verifica che il payload contenga sdi_code o recipient_pec per il destinatario.
4. Rileggi la risposta JSON di errore: il messaggio indica quale validazione ha fallito — non serve indovinare, il body della risposta è la fonte primaria.
5. Riprova prima in sandbox (vedi use-sandbox-environment) per isolare il problema senza toccare dati di produzione.

Configurazione correlata

Per i nomi canonici dei campi payload e i codici errore documentati, vedi api/sdi.