FAQ

Trova le risposte a 3 domande frequenti su E-INVOICE, organizzate per argomento.

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