Foreign counterparts and self-invoices

When you create an invoice via API, the request body is the FatturaPA format (JSON or XML): the fields you send are transmitted to the SDI and used to derive the counterpart. Because of this, some payload details — irrelevant for an Italian counterpart — become critical with foreign counterparts and with self-invoices.

This guide explains how to fill in those fields correctly.

IdFiscaleIVA: country and number must be separate

In the FatturaPA format the VAT number is split into two distinct fields inside IdFiscaleIVA:

• IdPaese → the 2-letter ISO country code (e.g. DE)
• IdCodice → the number only, without the country prefix (e.g. 123456789)

The most common mistake with foreign counterparts is putting the VAT number with its prefix (DE123456789) into IdCodice, while IdPaese is also DE. The result is a duplicated country code.

	IdPaese	IdCodice	How it renders
✅ Correct	DE	123456789	DE123456789
❌ Wrong	DE	DE123456789	DEDE123456789

Why it is a problem

The Agenzia delle Entrate fiscal-drawer viewer concatenates IdPaese + IdCodice. If IdCodice already contains the prefix, the VAT number is shown doubled (e.g. DEDE123456789). An Italian VAT number is an 11-digit number that never starts with IT, so the problem only occurs with foreign counterparts whose VAT starts with the country code.

info

Rule of thumb: IdCodice must always contain the plain number, without the country code. The country code goes only in IdPaese.

vatNumber vs taxNumber

Do not confuse the two identifiers:

• vatNumber → IdFiscaleIVA (VAT number): this is the one that must be split into IdPaese + IdCodice as explained above.
• taxNumber → CodiceFiscale: a separate field, a unique identifier with no country prefix.

Avoiding duplicate counterparts

When you create an invoice via API, Sibill recognises an already-existing counterpart only if all of these fields match those of a counterpart of the company:

company_id · country · tax_number · vat_number · company_name

This is an exact match on the combination of the five fields. As a result, if compared to a previous invoice even one of country, tax_number, vat_number or company_name changes — e.g. the VAT written with or without the country prefix, the name with or without KFT/GmbH, or a different IdPaese — the invoice is not linked to the existing counterpart and a new one is created.

How to avoid duplicates

Send the counterpart's identifying data consistently across all invoices:

• IdPaese = the correct ISO country code of the counterpart (not IT for foreign counterparts).
• IdCodice = VAT number without prefix, always in the same format.
• Company name always written the same way.

Example: invoice to a foreign counterpart (JSON)

Excerpt of the cessionario_committente (recipient) of an invoice to a private German company:

{
  "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"
      }
    }
  }
}

The same excerpt 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>

Self-invoices (TipoDocumento)

A self-invoice (or reverse-charge integration) is an invoice you issue to yourself to record a purchase — typically from a foreign supplier or under reverse charge. It differs from a normal invoice by the TipoDocumento (tipo_documento) field in the document's general data.

The most common TipoDocumento codes for self-invoices are:

Code	Typical use
TD16	Internal reverse-charge integration
TD17	Integration/self-invoice for purchase of services from abroad
TD18	Integration for intra-community purchase of goods
TD19	Integration/self-invoice for purchase of goods under art. 17 c. 2

note

In addition to these, Sibill also treats codes TD20–TD23 and TD27–TD29 as self-invoices (and TD26 only when seller and buyer are the same party). For the complete, official list of TipoDocumento codes, refer to the Agenzia delle Entrate FatturaPA specification.

Who is the counterpart in a self-invoice

In a self-invoice the document is a purchase (direction RECEIVED) and the roles map as follows:

• Your company is the cessionario/committente (the buyer).
• The counterpart (the supplier) is the cedente/prestatore.

So make sure your company's data is in cessionario_committente and the supplier's data is in cedente_prestatore, applying here too the IdPaese/IdCodice rules seen above if the supplier is foreign.

In short

• IdPaese = country code; IdCodice = number only (never DE123456789).
• Private counterparts (including foreign): always send formato_trasmissione: "FPR12".
• Consistent identifying data across all invoices to avoid duplicates.
• Self-invoice = TipoDocumento TD16–TD19 (and others): your company is the buyer, the counterpart is the seller.