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 il collegamento all'Agenzia delle Entrate del tuo esercente (Fisconline o CIE) e trasmette il documento in tempo reale.

Prerequisiti

• Account ScontrinoZero con piano Pro o Team attivo, oppure in prova gratuita (la prova include l'accesso API con una chiave; su Pro e Team le chiavi attive sono al massimo 3). Alla scadenza della prova le chiavi smettono di autenticare e tornano attive passando a Pro o Team, senza rigenerarle.
• Credenziali AdE collegate in Impostazioni → Credenziali AdE: Fisconline oppure CIE. Con la CIE la sessione va rinnovata di tanto in tanto dall'app; finché non lo fai, l'API risponde 409 ADE_REAUTH_REQUIRED.
• 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 prova gratuita basta per generare una chiave e integrare. Per testare anche il flusso di abbonamento — o il limite di 3 chiavi dei piani Pro e Team — attiva Pro con una carta di test Stripe: numero 4242 4242 4242 4242, scadenza una qualsiasi data futura, CVC tre cifre qualsiasi. Nessun addebito: il sandbox usa Stripe in modalità test, e la stessa carta viene rifiutata in produzione. L'elenco completo delle carte di test (3D Secure, pagamenti rifiutati) è nella documentazione Stripe.
• 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,
      "globalDiscount": "0.00",
      "paymentMethod": "PE",
      "payments": null,
      "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",
  "payments": null,
  "lotteryCode": "ABCD1234",
  "voidedDocumentId": null,
  "returnedDocumentId": null,
  "total": "18.50",
  "globalDiscount": "0.00",
  "lines": [
    {
      "description": "Pizza Margherita",
      "quantity": "2.000",
      "grossUnitPrice": "8.00",
      "lineDiscount": "0.00",
      "vatCode": "10",
      "returnedQuantity": "1.000"
    },
    {
      "description": "Acqua naturale",
      "quantity": "1.000",
      "grossUnitPrice": "2.50",
      "lineDiscount": "0.00",
      "vatCode": "10",
      "returnedQuantity": "0.000"
    }
  ]
}

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

POST/v1/receipts/{id}/return

Emette il documento commerciale di reso per uno o più articoli di uno scontrino (SALE) emesso con ScontrinoZero, e lo trasmette all'Agenzia delle Entrate. Il reso è irreversibile, può essere parziale e si può ripetere finché restano pezzi da rendere. Uno scontrino con almeno un reso non si può più annullare.

Corpo della richiesta

Esempio

curl -X POST https://api.scontrinozero.it/v1/receipts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/return \
  -H "Authorization: Bearer szk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "550e8400-e29b-41d4-a716-446655440002", "quantities": [1, 0]}'

Risposta — 200 OK

{
  "returnDocumentId": "e5f6a7b8-c9d0-1234-ef01-234567890123",
  "adeTransactionId": "151085591",
  "adeProgressive": "DCW2026/5111-2190"
}

Il reso si legge poi con GET /v1/receipts/{returnDocumentId}: kind vale RETURN, total è l'importo reso (positivo) e lines sono i pezzi resi, con la loro quota di sconto di riga.

Codici IVA

Il campo vatCode accetta i seguenti valori:

Idempotenza

Ogni richiesta di emissione, annullamento e reso 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 il risultato 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

Le finestre sono fisse e partono dalla prima richiesta: raggiunto il tetto, il contatore si azzera allo scadere della finestra (Retry-After indica i secondi mancanti). Emissione e lista hanno due finestre, un picco al minuto e una media oraria: vale la prima che si esaurisce. L'emissione conta per attività, non per chiave: tutte le chiavi e la cassa della stessa attività usano lo stesso contatore, perché trasmettono con la stessa utenza dell'Agenzia delle Entrate. Gli altri limiti sono per chiave API.

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 lo stesso oggetto JSON, su qualsiasi endpoint e qualsiasi status:

{
  "code": "PENDING_IN_PROGRESS",
  "message": "Una richiesta con la stessa idempotencyKey è ancora in corso.",
  "requestId": "9f1c2f5e-7b3a-4c1d-9e8f-2a6b0d4c7e11"
}

• code — stringa stabile: è il campo su cui costruire la logica del tuo client.
• message — testo pensato per una persona. Può cambiare senza preavviso: non farne parsing.
• requestId — identificativo della richiesta, presente anche nell'header X-Request-Id di tutte le risposte (successi inclusi). Citalo quando ci scrivi: ci permette di ritrovare la richiesta nei log.
• documentId — presente solo quando l'errore riguarda un documento già scritto: sugli esiti ancora aperti (ADE_UNAVAILABLE, DB_TIMEOUT, PENDING_IN_PROGRESS, VOID_PENDING_IN_PROGRESS, RETURN_PENDING_IN_PROGRESS) è l'id da interrogare con GET /v1/receipts/{id} per sapere come è andata a finire; su RETURN_SYNC_FAILED è l'id del reso, da citare quando ci scrivi. Sugli altri errori il campo non c'è.

Quando una risposta include l'header Retry-After, l'errore è temporaneo: attendi i secondi indicati e ripeti la richiesta identica, con la stessa idempotencyKey. Non generare mai una chiave nuova per un tentativo ripetuto: rischieresti un secondo scontrino, che non è più annullabile automaticamente.

Scontrini rimasti in sospeso

Uno scontrino resta in sospeso quando l'Agenzia delle Entrate non risponde alla trasmissione: ricevi un 503 ADE_UNAVAILABLE e l'esito è ignoto, perché il documento potrebbe essere già registrato. La mossa è una sola: ripeti la richiesta con la stessa idempotencyKey. Prima di ritrasmettere cerchiamo il documento sull'Agenzia delle Entrate e, se c'è già, lo colleghiamo a quella vendita invece di emetterne un secondo.

Se il tuo processo smette di ritentare, lo scontrino resta in sospeso e non compare nell'elenco, che di default mostra solo i documenti registrati. Due modi per ritrovarlo: il campo documentId dell'errore, da interrogare con GET /v1/receipts/{id}, e la lista filtrata per stato, che restituisce tutte le righe in sospeso del periodo.

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

Quando all'Agenzia delle Entrate risultano più documenti compatibili — stesso importo, emessi a pochi minuti di distanza da quello in sospeso — nessun automatismo sa quale sia il tuo, e lo scontrino resta in sospeso: sceglie l'esercente dall'app web ScontrinoZero, dove il banner in dashboard mostra i candidati e chiede quale riconosce.

Domande frequenti

Articoli correlati

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

Quando citiamo una norma indichiamo estremo e data, così puoi verificarla alla fonte. Informazione divulgativa: non sostituisce la consulenza del commercialista, e per situazioni specifiche vanno sempre verificati la normativa aggiornata e il tuo codice ATECO. Hai trovato un'imprecisione? Segnalacela a [email protected].