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 — for all your calls, receipts included. There is no way to run receipts on the old version alongside e-invoicing.
  • 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 is mandatory for SDI submission: two uppercase letters, for example MI or RM. 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: three requests to add the registration data

1. Suspend the Taxpayer — PATCH /taxpayers/{taxpayer_id}

{
  "content": {
    "mode": "SUSPENDED"
  }
}

2. Send the complete blocks — PATCH /taxpayers/{taxpayer_id}. Repeat your existing values and add registration (and region, if missing):

{
  "content": {
    "address": {
      "line": {
        "type": "STREET_NUMBER",
        "street": "Via Milano",
        "number": "42"
      },
      "code": "20121",
      "city": "Milano",
      "country": "IT",
      "region": "MI"
    },
    "fiscalization": {
      "type": "IT",
      "tax_id_number": "12345678901",
      "vat_id_number": "12345678901",
      "credentials": {
        "type": "FISCONLINE",
        "tax_id_number": "RSSMRA85M01H501Z",
        "password": "<your-password>",
        "pin": "<your-pin>"
      },
      "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"
      }
    }
  }
}

3. Set the Taxpayer back to operative — PATCH /taxpayers/{taxpayer_id}

{
  "content": {
    "mode": "OPERATIVE"
  }
}

Step 2 — Commission an additional System

Section titled “Step 2 — Commission an additional System”

Commissioning the E_INVOICE_SERVICE System is what makes e-invoicing possible for this Taxpayer — it’s what builds the FatturaPA XML, transmits it to SDI, and (optionally) receives inbound invoices. But it is not the System you send invoice records to.

Because this Taxpayer already has a FISCAL_DEVICE commissioned, that System takes precedence for record creation: you create the same INTENTION::TRANSACTION → TRANSACTION::INVOICE chain you already use for receipts, on a FISCAL_DEVICE System (any one on the same Taxpayer) — not on E_INVOICE_SERVICE. fiskaly reads that data and turns it into the e-invoice behind the scenes.

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 (any one on the same Taxpayer)
  • Credit note → create a TRANSACTION::CORRECTION with data.type=INVOICE on the same System, 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 a business outside Italy"XXXXXXX"not used

For a business outside Italy, send destination_code: "XXXXXXX" with the recipient’s foreign VAT number — see Business recipients outside Italy.

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 your FISCAL_DEVICE 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 the E_INVOICE::TRANSMISSION Record to learn whether SDI accepted it. There is no webhook.

If the invoice is transmitted, 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, read logs[].message: a failure before the invoice reaches SDI is logged on the TRANSACTION::INVOICE Record, an SDI rejection on the E_INVOICE::TRANSMISSION Record.

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.
Field validation (asynchronous)Invalid data in an accepted payload, e.g. a codice fiscale with a bad format or a wrong check digit, or a missing recipients[].address.regionThe Record closes COMPLETED / FINISHED with an ERROR entry in content.logs and no content.used_in. Nothing is transmitted. Fix the data and start a new chain.
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 the E_INVOICE::TRANSMISSION Record to get the SDI rejection reason
  2. Create a new INTENTION::TRANSACTION and a new TRANSACTION::INVOICE with corrected data
  3. A new 5-day window starts with the NS rejection. Within it, you can resend the invoice with the same document.number, as new Records with a new idempotency key
  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