E-INVOICE IT for SIGN IT customers

This guide is for customers who already have a working SIGN IT integration and want to add Italian B2B e-invoicing (E-INVOICE IT) on top of it. Both products run on the same Unified API and share the same Taxpayer and Location structure — only a few additions are needed.

What your SIGN IT integration already covers

Before starting, your integration is assumed to have:

• A Taxpayer created with Italian fiscalization data (fiscalization.type=IT, tax_id_number, vat_id_number, credentials)
• The Taxpayer commissioned (state=COMMISSIONED, mode=OPERATIVE)
• A FISCAL_DEVICE System commissioned on the Taxpayer’s Location
• An INTENTION::TRANSACTION → TRANSACTION::RECEIPT flow for fiscal receipts

None of this needs to change. The steps below add E-INVOICE IT alongside the existing setup.

Step 1 — Extend Taxpayer onboarding data

Two additions are required on the Taxpayer that SIGN IT alone does not need:

• address.region — the Italian Provincia code (e.g. MI, RM) is mandatory for SDI submission. If it is not already set on the Taxpayer, add it via updateTaxpayer.

• fiscalization.registration — a new block carrying Registro delle Imprese / REA data. Required fields: company_id, office, entry, legal_form, capital, shareholder_status, liquidation_status. tax_regime is optional (defaults to ORDINARY). This block is optional at the API level but is required by SDI for registered entities and should be provided at onboarding time.

Example: PATCH /taxpayers/{taxpayer_id}

{
  "content": {
    "address": {
      "region": "MI"
    },
    "fiscalization": {
      "type": "IT",
      "registration": {
        "company_id": "MI12345678901234567",
        "office": "MI",
        "entry": "1234567",
        "legal_form": "LIMITED_LIABILITY_COMPANY",
        "capital": "10000.00",
        "shareholder_status": "MULTIPLE_SHAREHOLDERS",
        "liquidation_status": "NOT_IN_LIQUIDATION"
      }
    }
  }
}

💡Already have address.region?

If your SIGN IT integration already collects the Taxpayer’s full address including region, no change is needed here — just add the registration block.

Step 2 — Commission an additional System

Use createSystem to create an E_INVOICE_SERVICE System on the Taxpayer’s Location, then commission it via updateSystem.

📘Note

Only one E_INVOICE_SERVICE System is needed per Taxpayer, linked to the HEAD_OFFICE Location — which is automatically created when the Taxpayer is created. This is separate from the FISCAL_DEVICE Systems used for receipt fiscalization, which are linked to individual BRANCH Locations and can exist in any number alongside it.

Step 3 — Add the invoice transaction flow

SIGN IT uses TRANSACTION::RECEIPT. E-INVOICE IT uses a different transaction type on the same INTENTION::TRANSACTION container:

• B2B invoice → create a TRANSACTION::INVOICE linked to the E_INVOICE_SERVICE System
• Credit note → create a TRANSACTION::CORRECTION with data.type=INVOICE, referencing the original invoice via record.id

📘B2B only

Only BUSINESS recipients are supported. The recipient must have an invoicing block of type SDI with a valid destination_code. B2C invoices are currently out of scope.

Handling SDI responses

Asynchronous outcome

Unlike receipt flows, the SDI outcome is asynchronous. After creating the TRANSACTION::INVOICE, poll or listen for updates on the E_INVOICE::TRANSMISSION Record.

💡Tip

SDI outcomes typically arrive within a few minutes. However, the SDI specification allows up to 48 hours.

All three Records reach their final state together:

Record	Final state
E_INVOICE::TRANSMISSION	COMPLETED or FAILED, mode=FINISHED
TRANSACTION::INVOICE	COMPLETED or FAILED, mode=FINISHED
INTENTION::TRANSACTION	COMPLETED or FAILED, mode=FINISHED

On failure, the SDI rejection reason is available in logs[].message on all three Records.

📘Note

The compliance artifact for Italian e-invoicing is the FatturaPA XML, accessible on the E_INVOICE::TRANSMISSION Record.

For more details, see How to check the status of an e-invoice on our Support page.

Error stages

Errors can occur at three distinct stages, each with different behavior:

Stage	When	Behavior
UAPI validation (synchronous)	Invalid payload	4xx returned immediately — no Record is created. Fix the payload and retry on the same INTENTION::TRANSACTION.
Invopop validation (asynchronous)	Invopop rejects before reaching SDI	Full chain reaches state=FAILED — a new chain is required to retry.
SDI rejection (asynchronous)	SDI returns NS	Full chain reaches state=FAILED — a new chain is required to retry.

Failures and resubmission

If SDI returns NS (Notifica di Scarto), the invoice is legally non-existent:

1. Read logs[].message on any of the three Records to get the SDI rejection reason
2. Create a new INTENTION::TRANSACTION and a new TRANSACTION::INVOICE with corrected data
3. The same document.number may be reused within 5 days of the NS rejection
4. The failed chain remains FAILED permanently — it is kept for audit purposes

⚠️No automatic retry

Each resubmission starts a fresh transaction chain — UAPI treats it as an entirely new submission.

What does not change

The following remain completely untouched:

• Taxpayer commissioning flow and Fisconline credentials
• All FISCAL_DEVICE Systems and BRANCH Locations
• Your existing INTENTION::TRANSACTION → TRANSACTION::RECEIPT receipt flow