Controparti estere e autofatture

Quando crei una fattura via API, il corpo della richiesta è il formato FatturaPA (JSON o XML): i campi che invii vengono trasmessi allo SDI e utilizzati per derivare la controparte. Per questo alcuni dettagli del payload — irrilevanti per una controparte italiana — diventano critici con controparti estere e con le autofatture.

Questa guida spiega come compilare correttamente questi campi.

`IdFiscaleIVA`: paese e numero vanno separati

Nel formato FatturaPA la partita IVA è divisa in due campi distinti dentro IdFiscaleIVA:

IdPaese → il codice paese ISO a 2 lettere (es. DE)
IdCodice → solo il numero, senza il prefisso paese (es. 123456789)

L'errore più comune con le controparti estere è mettere la partita IVA completa di prefisso (DE123456789) dentro IdCodice, lasciando IdPaese uguale a DE. Il risultato è un doppione del codice paese.

	`IdPaese`	`IdCodice`	Come appare
✅ Corretto	`DE`	`123456789`	`DE123456789`
❌ Sbagliato	`DE`	`DE123456789`	`DEDE123456789`

Perché è un problema

Il visualizzatore del cassetto fiscale dell'Agenzia delle Entrate concatena IdPaese + IdCodice. Se IdCodice contiene già il prefisso, la partita IVA viene mostrata raddoppiata (es. DEDE123456789). Una partita IVA italiana è un numero di 11 cifre che non inizia mai con IT, quindi il problema si presenta solo con le controparti estere la cui VAT inizia con il codice paese.

informazioni

Regola pratica: in IdCodice va sempre il numero puro, senza il codice paese. Il codice paese va solo in IdPaese.

`vatNumber` vs `taxNumber`

Non confondere i due identificativi:

vatNumber → IdFiscaleIVA (Partita IVA): è quello che va spezzato in IdPaese + IdCodice come spiegato sopra.
taxNumber → CodiceFiscale: campo separato, un identificativo unico senza prefisso paese.

Evitare controparti duplicate

Quando crei una fattura via API, Sibill riconosce una controparte già esistente solo se tutti questi campi coincidono con quelli di una controparte dell'azienda:

company_id · country · tax_number · vat_number · company_name

È una corrispondenza esatta sulla combinazione dei cinque campi. Di conseguenza, se rispetto a una fattura precedente cambia anche solo uno tra country, tax_number, vat_number o company_name — ad esempio la VAT scritta con o senza prefisso paese, il nome con o senza KFT/GmbH, o un IdPaese diverso — la fattura non viene agganciata alla controparte esistente e ne viene creata una nuova.

Come evitare i duplicati

Invia i dati identificativi della controparte in modo coerente su tutte le fatture:

IdPaese = codice ISO corretto del paese della controparte (non IT per controparti estere).
IdCodice = numero VAT senza prefisso, sempre nello stesso formato.
Nome azienda scritto sempre allo stesso modo.

Esempio: fattura a controparte estera (JSON)

Estratto del cessionario_committente (destinatario) di una fattura verso un'azienda tedesca privata:

{
  "fattura_elettronica_header": {
    "dati_trasmissione": {
      "formato_trasmissione": "FPR12",
      "codice_destinatario": "XXXXXXX"
    },
    "cessionario_committente": {
      "dati_anagrafici": {
        "id_fiscale_iva": {
          "id_paese": "DE",
          "id_codice": "123456789"
        },
        "anagrafica": {
          "denominazione": "Muster GmbH"
        }
      },
      "sede": {
        "indirizzo": "Musterstrasse 1",
        "cap": "10115",
        "comune": "Berlin",
        "nazione": "DE"
      }
    }
  }
}

Lo stesso estratto in XML:

<FatturaElettronicaHeader>
  <DatiTrasmissione>
    <FormatoTrasmissione>FPR12</FormatoTrasmissione>
    <CodiceDestinatario>XXXXXXX</CodiceDestinatario>
  </DatiTrasmissione>
  <CessionarioCommittente>
    <DatiAnagrafici>
      <IdFiscaleIVA>
        <IdPaese>DE</IdPaese>
        <IdCodice>123456789</IdCodice>
      </IdFiscaleIVA>
      <Anagrafica>
        <Denominazione>Muster GmbH</Denominazione>
      </Anagrafica>
    </DatiAnagrafici>
    <Sede>
      <Indirizzo>Musterstrasse 1</Indirizzo>
      <CAP>10115</CAP>
      <Comune>Berlin</Comune>
      <Nazione>DE</Nazione>
    </Sede>
  </CessionarioCommittente>
</FatturaElettronicaHeader>

Autofatture (`TipoDocumento`)

Un'autofattura (o integrazione/reverse charge) è una fattura che tu emetti verso te stesso per registrare un acquisto — tipicamente da fornitore estero o in reverse charge. Si distingue dalla fattura normale per il campo TipoDocumento (tipo_documento) nei dati generali del documento.

I codici TipoDocumento più comuni per le autofatture sono:

Codice	Uso tipico
`TD16`	Integrazione fattura reverse charge interno
`TD17`	Integrazione/autofattura per acquisto di servizi dall'estero
`TD18`	Integrazione per acquisto di beni intracomunitari
`TD19`	Integrazione/autofattura per acquisto di beni ex art. 17 c. 2

note

Oltre a questi, Sibill tratta come autofattura anche i codici TD20–TD23 e TD27–TD29 (e TD26 solo quando cedente e cessionario coincidono). Per l'elenco completo e ufficiale dei codici TipoDocumento fai riferimento alle specifiche FatturaPA dell'Agenzia delle Entrate.

Chi è la controparte in un'autofattura

In un'autofattura il documento è in acquisto (direzione RECEIVED) e i ruoli si mappano così:

La tua azienda è il cessionario/committente (chi acquista).
La controparte (il fornitore) è il cedente/prestatore.

Assicurati quindi che i dati della tua azienda siano nel cessionario_committente e quelli del fornitore nel cedente_prestatore, applicando anche qui le regole su IdPaese/IdCodice viste sopra se il fornitore è estero.

In sintesi

IdPaese = codice paese; IdCodice = solo numero (mai DE123456789).
Controparti private (anche estere): invia sempre formato_trasmissione: "FPR12".
Dati identificativi coerenti su tutte le fatture per non creare duplicati.
Autofattura = TipoDocumento TD16–TD19 (e altri): la tua azienda è il cessionario, la controparte è il cedente.

IdFiscaleIVA: paese e numero vanno separati​

vatNumber vs taxNumber​

Evitare controparti duplicate​

Esempio: fattura a controparte estera (JSON)​

Autofatture (TipoDocumento)​

Chi è la controparte in un'autofattura​

In sintesi​