API per sviluppatori

Le API REST di ScontrinoZero permettono di integrare l'emissione di scontrini elettronici direttamente nel tuo gestionale, POS o e-commerce. Ogni chiamata usa le credenziali Fisconline del tuo esercente e trasmette il documento all'Agenzia delle Entrate in tempo reale.

Prerequisiti

• Account ScontrinoZero con Piano Pro attivo.
• Credenziali Fisconline configurate nella sezione Configurazione attività.
• Una chiave API di tipo business generata dalla dashboard: vai su Impostazioni → Altre impostazioni → API key, clicca + Nuova API key, assegnale un nome descrittivo (es. "POS principale"), clicca Genera e copia la chiave — sarà mostrata una sola volta.

Autenticazione

Includi la chiave API in ogni richiesta tramite l'header Authorization:

Authorization: Bearer szk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Base URL

https://api.scontrinozero.it/v1

Sandbox

Per sviluppare e testare la tua integrazione senza emettere scontrini reali all'Agenzia delle Entrate, usa l'ambiente sandbox:

https://api-sandbox.scontrinozero.it/v1

Il sandbox è identico alla produzione, ma ogni chiamata all'AdE è simulata — nessun documento viene trasmesso. Le risposte hanno la stessa struttura di quelle reali; il campo adeProgressive è fittizio e contiene il prefisso MOCK- (es. DCW2026/MOCK-1).

• Registra un account separato su sandbox.scontrinozero.it (non collegato alla produzione).
• Le credenziali Fisconline accettano qualsiasi valore nel sandbox.
• I dati sandbox possono essere resettati senza preavviso.
• La chiave API sandbox inizia sempre con szk_live_ — è un token di accesso all'ambiente sandbox, non alla produzione.

Endpoint

POST/v1/receipts

Emette uno scontrino elettronico e lo trasmette all'Agenzia delle Entrate.

Corpo della richiesta

Esempio

curl -X POST https://api.scontrinozero.it/v1/receipts \
  -H "Authorization: Bearer szk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      {
        "description": "Pizza Margherita",
        "quantity": 2,
        "grossUnitPrice": 8.00,
        "vatCode": "10"
      },
      {
        "description": "Acqua naturale",
        "quantity": 1,
        "grossUnitPrice": 2.50,
        "vatCode": "10"
      }
    ],
    "paymentMethod": "PE",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "lotteryCode": "ABCD1234"
  }'

Risposta — 201 Created

{
  "documentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "adeTransactionId": "151085589",
  "adeProgressive": "DCW2026/5111-2188"
}

GET/v1/receipts

Restituisce la lista paginata degli scontrini emessi nell'intervallo di date indicato. Utile per riconciliazione contabile, export periodico o sync verso sistemi gestionali.

Parametri query

Esempio

curl "https://api.scontrinozero.it/v1/receipts?from=2026-04-01&to=2026-04-30&limit=100" \
  -H "Authorization: Bearer szk_live_XXXX"

Se sono stati emessi più di 100 scontrini nel periodo, usa &page=2, &page=3, ecc. Il campo pagination.hasNextPage indica se esistono ulteriori pagine.

Risposta — 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
      "kind": "SALE",
      "status": "ACCEPTED",
      "adeTransactionId": "151085589",
      "adeProgressive": "DCW2026/5111-2188",
      "lotteryCode": null,
      "paymentMethod": "PE",
      "total": "18.50",
      "createdAt": "2026-04-05T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1,
    "hasNextPage": false
  }
}

La risposta non include le righe di dettaglio. Per il contenuto completo di uno scontrino usa GET /v1/receipts/{id} (campo lines incluso).

GET/v1/receipts/{id}

Restituisce i dettagli e lo stato di uno scontrino emesso. Utile per verificare l'esito di un'emissione o per implementare l'idempotency check sul tuo client.

Esempio

curl https://api.scontrinozero.it/v1/receipts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer szk_live_XXXX"

Risposta — 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "kind": "SALE",
  "status": "ACCEPTED",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "adeTransactionId": "151085589",
  "adeProgressive": "DCW2026/5111-2188",
  "createdAt": "2026-03-26T10:00:00.000Z",
  "paymentMethod": "PE",
  "lotteryCode": "ABCD1234",
  "voidedDocumentId": null,
  "total": "18.50",
  "lines": [
    {
      "description": "Pizza Margherita",
      "quantity": "2.000",
      "grossUnitPrice": "8.00",
      "vatCode": "10"
    },
    {
      "description": "Acqua naturale",
      "quantity": "1.000",
      "grossUnitPrice": "2.50",
      "vatCode": "10"
    }
  ]
}

POST/v1/receipts/{id}/void

Annulla uno scontrino precedentemente emesso. L'annullamento è irreversibile e viene trasmesso all'Agenzia delle Entrate.

Corpo della richiesta

Esempio

curl -X POST https://api.scontrinozero.it/v1/receipts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/void \
  -H "Authorization: Bearer szk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "b2c3d4e5-f6a7-8901-bcde-f01234567890"}'

Risposta — 200 OK

{
  "voidDocumentId": "c3d4e5f6-a7b8-9012-cdef-012345678901",
  "adeTransactionId": "151085590",
  "adeProgressive": "DCW2026/5111-2189"
}

Codici IVA

Il campo vatCode accetta i seguenti valori:

Idempotenza

Ogni richiesta di emissione e annullamento richiede un campo idempotencyKey: un UUID v4 univoco che identifichi quella specifica operazione.

Se invii la stessa richiesta due volte con lo stesso idempotencyKey (es. in seguito a un timeout di rete), il sistema restituisce ilrisultato dell'operazione originale senza emettere un secondo scontrino. Genera una nuova chiave per ogni scontrino distinto.

// Esempio generazione in JavaScript
const idempotencyKey = crypto.randomUUID();

Rate limiting

I limiti sono per chiave API, con finestra scorrevole di 1 ora:

Al superamento del limite ricevi una risposta 429 con header Retry-After che indica i secondi da attendere prima di riprovare.

Codici di errore

Tutti gli errori restituiscono un oggetto JSON con il campo error:

{ "error": "Descrizione dell'errore." }

Articoli correlati

• Come emettere il primo scontrino elettronico
• Sicurezza e privacy delle credenziali
• Come contattare l'assistenza