FAQ

Encuentre respuestas a 5 preguntas frecuentes sobre E-INVOICE, organizadas por tema.

Italy (2)

How to represent payments on an invoice

Payments are carried in payments[] on the invoice operation. The array accepts between 1 and 10 entries. Which fields you provide depends on whether the invoice has already been settled.

 

Payment already received

Select the payment type that applies — CASH, CARD, ONLINE, VOUCHER or OTHER — and provide details.amount.  Some types require additional fields:

Type	Additional required fields
CASH	—
CARD	number, kind
VOUCHER	number, kind
ONLINE	name
OTHER	— (name is optional)
Optionally, details can also carry date , discount and properties. The currency of the first payment in the array sets the currency of the whole invoice and  EUR is the only accepted value.

Payments of these types count as already settled — they reduce the amount the buyer still owes on the invoice. There are 2 possible scenarios:

• If they cover the invoice total, nothing further is needed.

• If they don’t, add an OUTSTANDING payment for the remainder; otherwise the invoice is rejected because the amounts don’t add up.

Payment still outstanding

Use payments[].type: "OUTSTANDING". payments[].concept is required and indicates whether the outstanding amount concerns a GOOD, a SERVICE, or an INVOICE. 

OUTSTANDING takes a details object: 

• details.amount is required and carries the amount still due.

• details.date is also required and sets the payment due date — an outstanding payment without a due date is rejected.

If you send more than one OUTSTANDING payment, only the first one is used. The others are ignored, and a warning is recorded on the invoice record.

• Payment instruction The instruction object is optional. Add it when the invoice should tell the buyer how to pay — for a bank transfer, it carries the IBAN the buyer should send the money to.

If you leave it out, the invoice is still accepted and transmitted. fiskaly then reports the payment method as a bank transfer, without any account details. So include an instruction when you want your account details on the invoice, or when the buyer is meant to pay some other way (by SEPA direct debit, for example).

When instruction is provided, instruction.type is CREDIT_TRANSFER or DIRECT_DEBIT. An instruction missing any of these fields is rejected:

 

CREDIT_TRANSFER requires type, account, name and payment_service_provider — all four. The IBAN goes in account, in ISO 13616 format (15–34 characters). payment_service_provider is the bank’s BIC/SWIFT code (e.g. BCITITMM) — a bank name is not accepted.

• DIRECT_DEBIT requires type, mandate_reference, creditor_id and debited_account, with the IBAN in debited_account. 

Note that creditor_id is an object rather than a string — { "type": "SEPA", "identifier": "IT05ZZZ12345678901" } — and the identifier is to match the SEPA creditor identifier format (9–35 characters), where the character following the three-letter business code is a digit.

Both variants also accept the optional fields text and properties. ** **Properties has a different shape depending on where it appears: on details it is an object of up to 16 entries whose values are strings of up to 64 characters, while on instruction it is a single string of up to 128 characters.

Note: instruction.type: “UNKNOWN” is not supported for Italy. It exists to allow text and properties without a credit transfer or direct debit, and is relevant for other E-INVOICE countries. Sending it for Italy returns a validation error requiring the it-sdi-payment-means extension.

 

Example of outstanding payment via bank transfer

{
  "payments": [
    {
      "type": "OUTSTANDING",
      "concept": "INVOICE",
      "details": {
        "amount": "122.00",
        "date": "2026-09-30"
      },
      "instruction": {
        "type": "CREDIT_TRANSFER",
        "account": "IT60X0542811101000000123456",
        "name": "Officina Rossi S.r.l.",
        "payment_service_provider": "BCITITMM"
      }
    }
  ]
}

 

Field	In the example
details.amount	The amount still due — not the invoice total
details.date	The payment due date — not the issue date
account	Your IBAN — the account the money arrives in
name	The holder of that account, i.e. you, the invoice issuer
payment_service_provider	The BIC/SWIFT code of your bank — not its name

Note: ModalitaPagamento is not a field you set. It is derived from the payment instruction on the outstanding payment, or defaulted to MP05 when no instruction is given. Bank transfer and SEPA direct debit are covered. Cheque and Riba are not currently supported — if you need them, contact fiskaly support so we can record the requirement.

 

Example of outstanding payment via SEPA direct debit

Only the instruction object differs from the bank transfer example above; type, concept and details are unchanged.

{
  "instruction": {
    "type": "DIRECT_DEBIT",
    "mandate_reference": "MANDATE-2026-0042",
    "creditor_id": {
      "type": "SEPA",
      "identifier": "IT05ZZZ12345678901"
    },
    "debited_account": "IT60X0542811101000000123456"
  }
}

Field	In this example
mandate_reference	Your reference for the SEPA mandate the buyer signed
creditor_id.identifier	Your SEPA creditor identifier — you collect the money
debited_account	The buyer’s IBAN — the account you debit

Note the direction: in a credit transfer the IBAN is yours and the buyer pushes the money; in a direct debit the IBAN is the buyer’s and you pull it.

Which VAT rates and exemptions can be used in Italy?

This article provides a detailed mapping of VAT rates and exemptions applicable in Italy when using E-INVOICE IT for the sending of e-invoices.

VAT rates

vat.code	vat.percentage	Typical use cases
STANDARD	22%	Default rate for anything not expressly reduced
REDUCED_1	10%	Tourism/hospitality, restaurants, construction works, domestic energy, some foods and pharmaceuticals
REDUCED_2	5%	Certain social/care services, some essential goods, works of art
REDUCED_3	4%	Staple foods, books and newspapers, first homes, aids for the disabled

Note: Currently, the code is not cross-validated against the percentage. The applied VAT treatment is determined solely by the percentage field, not by the code field.  

VAT exemptions

Natura codes are the official exemption codes required by the Italian tax authority (Agenzia delle Entrate) for FatturaPA invoices, tied to specific articles of the Italian VAT law.

vat.code	Natura code	Description
CAUSE_1	N1	Excluded ex art. 15 DPR 633/72 (Escluse ex art. 15 DPR 633/72)
CAUSE_5	N2.1	Not subject to VAT under arts. 7–7-septies DPR 633/72 (Non soggette ad IVA ai sensi degli artt. da 7 a 7-septies del DPR 633/72)
CAUSE_6	N2.2	Not subject - other cases (Non soggette - altri casi)
CAUSE_7	N3.1	Not taxable - exportations (Non imponibili - esportazioni)
CAUSE_8	N3.2	Not taxable - intra-Community transfers (Non imponibili - cessioni intracomunitarie)
CAUSE_9	N3.3	Not taxable - transfers to San Marino (Non imponibili - cessioni verso San Marino)
CAUSE_10	N3.4	Not taxable - transactions treated as export supplies (Non imponibili - operazioni assimilate alle cessioni all’esportazione)
CAUSE_11	N3.5	Not taxable - declaration of intent (Non imponibili - a seguito di dichiarazioni d’intento)
CAUSE_12	N3.6	Not taxable - other, non-plafond-forming transactions (Non imponibili - altre operazioni che non concorrono alla formazione del plafond)
CAUSE_2	N4	Exempt (Esenti)
CAUSE_3	N5	Marginal scheme (Regime del margine)
CAUSE_13	N6.1	Reverse charge - transfer of scrap and other recyclable materials (Inversione contabile — cessione di rottami)
CAUSE_14	N6.2	Reverse charge - transfer of gold and silver (L. 7/2000), used jewelry to OPO (Inversione contabile - cessione di oro e argento ai sensi della legge 7/2000 nonché di oreficeria usata ad OPO)
CAUSE_15	N6.3	Reverse charge - subcontracting in the construction sector (Inversione contabile — subappalto nel settore edile)
CAUSE_16	N6.4	Reverse charge - transfer of buildings (Inversione contabile — cessione di fabbricati)
CAUSE_17	N6.5	Reverse charge - transfer of mobile phones (Inversione contabile — cessione di telefoni cellulari)
CAUSE_18	N6.6	Reverse charge - transfer of electronic products (Inversione contabile — cessione di prodotti elettronici)
CAUSE_19	N6.7	Reverse charge - provisions in the construction and related sectors (Inversione contabile — prestazioni comparto edile e settori connessi)
CAUSE_20	N6.8	Reverse charge - transactions in the energy sector (Inversione contabile — operazioni settore energetico)
CAUSE_21	N6.9	Reverse charge - other cases (Inversione contabile — altri casi)
CAUSE_22	N7	VAT paid in another EU country (IVA assolta in altro stato UE)

Note: VAT validation on the document only checks that totals.vat (amount, exclusive, inclusive) matches the amount recalculated from entries[]. Any discrepancy raises a non-blocking warning, as the transmitted document always uses the recalculated value, not the declared totals.vat.

General (2)

Which token do I need and when do I need to create one?

The integration guide describes two separate token creation steps (Step 4 and Step 7). This can be confusing — especially if your organization is already set up and you just want to send e-invoices. Here’s what each token is for and which one you actually need.

The two tokens explained

The API is split into two groups of endpoints: Management and Operation. Each group requires a token scoped to a different level.

Group-level token (Step 4) — for Management

This token is created using the API Key generated in the HUB at the Group level. It authenticates you for the Management endpoints:

• POST /organizations — create an Organization UNIT

• POST /subjects — create a new API Key scoped to a UNIT

• GET /subjects — list existing API Keys

You only need this token during the initial setup when creating your Organization UNIT and generating the UNIT-scoped API Key. Once those resources exist, you don’t need to create this token again unless you’re onboarding a new UNIT.

UNIT-scoped token (Step 7) — for Operation

This token is created using the API Key that was generated in Step 6 (the one scoped to your Organization UNIT via the X-Scope-Identifier header). It authenticates you for all Operation endpoints:

• POST /taxpayers — create and manage taxpayers

• POST /systems — create and manage systems

• POST /records — create records (intentions, transactions, uploads)

• GET /records/{record_id} — retrieve record status

• All other taxpayer, location, system, record, and file endpoints

Quick reference

I want to…	Token needed	How to create it
Set up a new Organization UNIT	Group-level	POST /tokens with HUB API Key
Create a new UNIT-scoped API Key	Group-level	POST /tokens with HUB API Key
Create/commission a Taxpayer	UNIT-scoped	POST /tokens with UNIT API Key
Create/commission a System	UNIT-scoped	POST /tokens with UNIT API Key
Upload Proof of Ownership	UNIT-scoped	POST /tokens with UNIT API Key
Send e-invoices (day-to-day)	UNIT-scoped	POST /tokens with UNIT API Key
Issue a credit note	UNIT-scoped	POST /tokens with UNIT API Key

How to check the status of an e-invoice?

When creating an invoice Record (TRANSACTION::INVOICE), a transmission Record (E_INVOICE::TRANSMISSION) is also created alongside to track the delivery of the e-invoice. 

Note: A TRANSACTION::INVOICE in COMPLETED state and FINISHED mode does not necessarily mean the e-invoice was delivered. Diagnostic logs on both Records should be checked to identify any issues.

Step 1: Retrieve the TRANSACTION::INVOICE Record

When creating a TRANSACTION::INVOICE, save the record id from the API response. Then retrieve it using:

GET /records/{{record_id}}

In the response, check the content.logs field:

• If it contains entries with "severity": "ERROR", the invoice failed validation before any transmission was attempted. To resolve the issue, review the error message, correct the request payload accordingly, and create a new TRANSACTION::INVOICE Record with a new idempotency key.

• If content.logs is empty, validation passed and the e-invoice was submitted for transmission. Proceed to Step 2.

Step 2: Retrieve the E_INVOICE::TRANSMISSION Record

In the TRANSACTION::INVOICE response from Step 1, locate the content.used_in.id field. This is the ID of the E_INVOICE::TRANSMISSION Record. Retrieve it using:

GET /records/{{content.used_in.id}}

Check the content.logs field:

• If it contains ERROR entries, the e-invoice could not be delivered over the e-invoice network. The message field describes what went wrong. To resolve the issue, review the error message, correct the request payload accordingly, and create a new TRANSACTION::INVOICE Record with a new idempotency key.  If the error indicates a network or infrastructure issue, retry after a short delay.  If the issue persists, contact fiskaly support.

 

• If content.logs is empty on both Records, the transmission may still be in progress. E-invoice delivery is handled asynchronously and typically completes within seconds to minutes.  If the logs remain empty after several minutes, contact fiskaly support.

Reading a log entry

Each log entry contains the following fields:

Field	Description
severity	ERROR (a failure that prevented delivery) or WARNING (a non-fatal issue, the operation still proceeded).
message	A human-readable description of the issue.
code	A machine-readable code to categorize the log.
date	The timestamp when the log was created.

Example

[
  {
    "$": "Log@v1",
    "date": "2026-05-13T08:32:18.214995449Z",
    "message": "invalid Belgian VAT ID length '12'",
    "severity": "ERROR"
  },
  {
    "$": "Log@v1",
    "date": "2026-05-13T08:32:18.30059009Z",
    "message": "e_invoicing failed: code: invalid format.",
    "severity": "ERROR"
  }
]

 

Note: WARNING logs are informational and do not affect the transmission of the e-invoice.

Belgium (1)

What is the difference between tax_id_number and vat_id_number for Belgian taxpayers?

When creating a Belgian taxpayer via POST /taxpayers, the fiscalization object requires both a tax_id_number and a vat_id_number. These are two distinct identifiers that serve different purposes and are validated independently — even though for some Belgian companies the numeric value may be the same.

In all cases, provide only the numeric digits. Do not include dots, spaces, or any country prefix.

tax_id_number — KBO/BCE Enterprise Number

This is the company registration number issued by the Belgian Crossroads Bank for Enterprises (Kruispuntbank van Ondernemingen / Banque-Carrefour des Entreprises).

• Format: 9 or 10 digits

• Pattern: ^[01]?\d{9}$

• Example: 0123456789 or 123456789

vat_id_number — Belgian VAT Identification Number (VATIN)

This is the VAT registration number used for tax purposes.

• Format: Exactly 10 digits

• Pattern: ^[0-9]{10}$

• Example: 0123456789

Example: Belgian fiscalization block

 

JSON:

{
  "type": "BE",
  "tax_id_number": "0123456789",
  "vat_id_number": "0123456789",
  "credentials": {
    "type": "MYMINFIN"
  }
}

credentials.type must be set to MYMINFIN for Belgian taxpayers.

Common mistakes

Mistake	What happens
Including the BE prefix in vat_id_number (e.g. "BE0123456789")	Rejected — the pattern only allows digits
Swapping the two fields	May cause validation or transmission errors
Including dots or spaces (e.g. "0123.456.789")	Rejected — only digits are accepted
Providing a vat_id_number with fewer than 10 digits	Rejected — exactly 10 digits required