Skip to content
Guide API Spec
Section navigation

E-INVOICE IT for SIGN IT customers

You are viewing the documentation for API version 2026-06-01.

This guide is for customers who already have a working SIGN IT integration and want to add Italian e-invoicing (E-INVOICE IT) — B2B and B2C — 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.

Coming from SIGN IT 2024-10-31 or 2025-08-12? Expand and read this first.

After version 2025-08-12, some resources were renamed and new ones were added for e-invoicing. The updated endpoints can be called with the same {id} already in use.

Until version 2025-08-12After version 2025-08-12Notes
ASSET — /assetsORGANIZATION — /organizationsJust a rename — same ID as before.
ENTITY (COMPANY/INDIVIDUAL) — /entitiesTAXPAYER (COMPANY/INDIVIDUAL) — /taxpayersJust a rename — same ID as before.
ENTITY (LOCATION) — /entitiesLOCATION — /locationsThis resource is now split into two types:
  • HEAD_OFFICE location: created automatically at Taxpayer creation — same ID as your old ENTITY (COMPANY/INDIVIDUAL)
  • BRANCH location: any extra location. Created via the createLocation endpoint — same ID as your old ENTITY (LOCATION)
SYSTEM referencing entity: {id}SYSTEM referencing location: {id}Just a rename — same ID as before.

Before you continue:

  • Update your X-Api-Version header to the version shown in the banner above.
  • Make sure you’re pointing to the correct base URLs: test.api.fiskaly.com (TEST) and live.api.fiskaly.com (LIVE).
  • Add fiscalization.credentials.tax_id_number to your FISCONLINE credentials, if it isn’t already there. This field wasn’t required in 2024-10-31, was optional in 2025-08-12, but is now required.
  • Review the key record payload structure updates in the API doc — this FAQ may help along the way. For any questions, feel free to contact dev-support@fiskaly.com.

What your SIGN IT integration already covers

Section titled “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 / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION flow for fiscal receipts

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

1

Extend Taxpayer onboarding data

Add the extra company registration details that Italian e-invoicing requires.

2

Commission an additional System

Enable the e-invoicing service on your Taxpayer — this covers sending and, optionally, receiving.

3

Add the invoice transaction flow

Start issuing invoices and credit notes to businesses and consumers.

Step 1 — Extend Taxpayer onboarding data

Section titled “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. The tax_regime field defaults to ORDINARY if you don’t set it.

    SDI requires this block for registered entities, so provide it when you onboard the Taxpayer.

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

Step 2 — Commission an additional System

Section titled “Step 2 — Commission an additional System”

The E_INVOICE_SERVICE System is the only System that creates and transmits e-invoices (and receives inbound ones). It doesn’t replace your FISCAL_DEVICE Systems: you still create the invoice record (TRANSACTION::INVOICE) on a FISCAL_DEVICE System (any one on the same Taxpayer), and the E_INVOICE_SERVICE System turns that data into the e-invoice.

Use createSystem to create an E_INVOICE_SERVICE System on the Taxpayer’s HEAD_OFFICE Location, then commission it via updateSystem by setting its state to COMMISSIONED.

For the full receiving flow, see Receiving e-invoices on the Italy page.

Step 3 — Add the invoice transaction flow

Section titled “Step 3 — Add the invoice transaction flow”

SIGN IT uses TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION.

E-INVOICE IT uses different transaction types on the same INTENTION::TRANSACTION container:

  • Invoice (B2B or B2C) → create a TRANSACTION::INVOICE on a FISCAL_DEVICE System (as in Step 2)
  • Credit note → create a TRANSACTION::CORRECTION with data.type=INVOICE, referencing the original invoice via record.id

Both BUSINESS and CONSUMER recipients are supported. For a business recipient, the entry in the invoice’s recipients array needs an invoicing block of type SDI, plus the recipient’s Provincia:

  • recipients[].type = BUSINESS
  • recipients[].invoicing.type = SDI
  • recipients[].invoicing.destination_code — the recipient’s 7-character SDI inbox code
  • recipients[].invoicing.pec — (where required) the recipient’s PEC address
  • recipients[].address.region — the recipient’s Provincia (e.g. MI, RM)
Scenariodestination_codepec
Recipient has a registered SDI inboxtheir 7-character code, uppercase letters and digits (e.g. ABC1234)optional
Recipient is not registered with SDI"0000000"required
Recipient is outside Italy"XXXXXXX"not used

For a consumer recipient (B2C), the fields are different — no destination_code of your recipient’s choosing and no VAT number, but the codice fiscale is mandatory:

  • recipients[].type = CONSUMER
  • recipients[].identification.type = TAX, with number set to the consumer’s codice fiscale
  • recipients[].name — gender, forename and surname
  • recipients[].address — the consumer’s residence address, including region (Provincia)
  • recipients[].invoicing.destination_code = "0000000", with pec optional

For the full recipient requirements, see Sending e-invoices on the Italy page.

When a customer needs an invoice instead of a receipt

Section titled “When a customer needs an invoice instead of a receipt”

Your two flows report to different places — the receipt to the AdE, the invoice to SDI — and nothing links them automatically.

Capture the request before the sale is closed. When the customer tells you they need a fattura, issue a TRANSACTION::INVOICE on the E_INVOICE_SERVICE System in place of the receipt. That is the flow fiskaly supports end to end today, whether the customer asks before or during the sale.

Handling SDI responses

Section titled “Handling SDI responses”

Asynchronous outcome

Section titled “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.

All three Records reach their final state together:

RecordFinal state
E_INVOICE::TRANSMISSIONCOMPLETED or FAILED, mode=FINISHED
TRANSACTION::INVOICECOMPLETED or FAILED, mode=FINISHED
INTENTION::TRANSACTIONCOMPLETED or FAILED, mode=FINISHED

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

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

Sent and received e-invoices are automatically preserved long-term (conservazione a norma, at least 10 years), with a preservation receipt available from the Record’s archive-artifact. No setup is required. See Archiving on the Italy page for details.

Error stages

Section titled “Error stages”

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

StageWhenBehavior
UAPI validation (synchronous)Invalid payload4xx returned immediately — no Record is created. Fix the payload and retry on the same INTENTION::TRANSACTION.
Pre-SDI validation (asynchronous)The invoice is rejected before reaching SDIFull chain reaches state=FAILED — a new chain is required to retry.
SDI rejection (asynchronous)SDI returns NSFull chain reaches state=FAILED — a new chain is required to retry.

Failures and resubmission

Section titled “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

What does not change

Section titled “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 / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION receipt flow