Corrispettivi Elettronici (E-Receipts)

L'API Corrispettivi Elettronici permette di emettere, trasmettere e gestire gli scontrini digitali verso l'Agenzia delle Entrate attraverso un'unica integrazione. La soluzione è progettata per automatizzare l'intero processo di emissione dei documenti commerciali, semplificando la gestione fiscale di punti vendita fisici e software gestionali.

Con Openapi puoi configurare aziende, sedi operative, punti vendita (Store), registratori telematici e cassieri, creando un'infrastruttura completa per la gestione dei corrispettivi elettronici. Una volta completata la configurazione, ogni punto vendita è pronto per emettere documenti commerciali, gestire resi, annullamenti e monitorare tutte le operazioni tramite API.

L'API supporta l'intero ciclo di vita del corrispettivo elettronico: dalla configurazione iniziale fino all'emissione, alla consultazione e alla gestione delle operazioni successive, garantendo un'integrazione scalabile e adatta anche a reti con più punti vendita.

La soluzione è progettata per software gestionali, sistemi POS, ERP, piattaforme retail e applicazioni che desiderano integrare la gestione dei corrispettivi elettronici direttamente nei propri flussi operativi.

Tutte le operazioni vengono gestite tramite un'infrastruttura dedicata ai Corrispettivi Elettronici, consentendo di amministrare l'intero ambiente da un'unica integrazione API.

Configurazione azienda, punti vendita e registratori di cassa

POST /IT-configurations

La configurazione rappresenta il primo passaggio per utilizzare l'API Corrispettivi Elettronici. Tramite questo endpoint puoi registrare la tua azienda e predisporre l'intera infrastruttura necessaria alla gestione dei documenti commerciali.

Durante questa fase è possibile configurare la sede dell'azienda, creare uno o più Store (punti vendita), associare i registratori telematici a ciascun punto vendita e predisporre i callback per ricevere notifiche automatiche sulle operazioni eseguite dall'API.

Ogni Store può gestire uno o più registratori telematici, mentre ogni corrispettivo elettronico potrà essere associato al registratore utilizzato per l'emissione del documento commerciale.

ESEMPIO RICHIESTA

Per configurare l'azienda è sufficiente effettuare una richiesta al servizio POST /IT-configurations. Nell'esempio seguente vengono registrati l'azienda, la sede legale, un punto vendita con due registratori telematici e le callback per ricevere automaticamente gli aggiornamenti delle operazioni.

ESEMPIO RISPOSTA

Se la configurazione viene completata correttamente, l'API restituisce i dati dell'azienda registrata insieme ai servizi abilitati, alla configurazione dei punti vendita e dei registratori di cassa associati. La risposta conferma inoltre l'attivazione della configurazione e restituisce l'identificativo univoco che verrà utilizzato nelle successive operazioni di gestione.

{
  "data": {
    "id": "679ca42e**********016df7",
    "fiscal_id": "YourCompanyFiscal_id",
    "name": "nameCompany",
    "email": "[email protected]",
    "active": true,
    "receipts": true,
    "customer_invoice": true,
    "supplier_invoice": true,
    "merchant_address": {
      "street_address": "Via Roma",
      "street_number": "10",
      "zip_code": "00100",
      "city": "Roma",
      "province": "RM"
    },
    "stores": [
      {
        "label": "Negozio Centro",
        "cash_registers": [
          {
            "label": "Cassa 1"
          },
          {
            "label": "Cassa 2"
          }
        ]
      }
    ],
    "receipts_authentication": {
      "taxCode": "FHHWMF96L52D111B"
    },
    "api_configurations": [
      {
        "event": "receipt",
        "callback": {
          "method": "JSON",
          "url": "https://www.mysite.com/myEndpoint",
          "field": "data",
          "retry": 0
        }
      }
    ],
    "create_timestamp": 1738318895
  },
  "success": true,
  "message": "",
  "error": null
}

Emissione dei corrispettivi elettronici

POST /IT-e-receipts

L'endpoint POST /IT-e-receipts consente di emettere una ricevuta elettronica (Corrispettivo) per i punti vendita fisici. Il documento viene trasmesso utilizzando lo Store (PEM) e il registratore di cassa configurati in precedenza tramite il servizio IT-configurations.

Per utilizzare il servizio è necessario aver abilitato l'opzione e_receipts nella configurazione aziendale, utilizzare una Partita IVA valida come fiscal_id e aver completato la configurazione di almeno un punto vendita con il relativo registratore di cassa.

Durante l'emissione del documento è possibile specificare il cassiere, il punto vendita e il registratore di cassa da utilizzare. L'API verifica automaticamente la titolarità delle risorse indicate e utilizza automaticamente la configurazione associata allo Store e al registratore di cassa selezionati.

Per impostazione predefinita viene emesso uno scontrino di vendita (type: sale). Lo stesso servizio supporta anche scenari avanzati, come prove d'acquisto, resi e annullamenti, attraverso gli endpoint e gli schemi dedicati previsti dalla documentazione.

ESEMPIO RICHIESTA

Per emettere un corrispettivo elettronico è necessario effettuare una richiesta a POST /IT-e-receipts. Nell'esempio seguente viene emesso uno scontrino di vendita (type: sale) associato a un punto vendita, un registratore di cassa e un cassiere già configurati. Il documento contiene una voce di vendita e un pagamento elettronico pari all'importo totale del corrispettivo.

{
  "fiscal_id": "11122211133",
  "type": "sale",
  "cashier_id": "69d7c469f6d16f5f4003eca6",
  "store_id": "69ca63ce0f8c187ebf0aa36c",
  "cr_id": "69d8cfbba3ccba0fcc0d0184",
  "items": [
    {
      "type": "goods",
      "id": 1,
      "quantity": "4.00",
      "description": "Mouse wireless premium",
      "unit_price": "2.00",
      "vat_rate_code": "22.00"
    }
  ],
  "electronic_payment_amount": "8.00"
}

Consultazione dei corrispettivi elettronici

GET /IT-e-receipts

L'endpoint GET /IT-e-receipts permette di consultare tutti i corrispettivi elettronici emessi tramite l'API. È possibile monitorare le operazioni effettuate dai diversi punti vendita.

La ricerca può essere filtrata utilizzando diversi parametri, consentendo di individuare facilmente uno o più documenti in base alle esigenze dell'applicazione. Questa funzionalità risulta particolarmente utile per software gestionali, ERP e sistemi di reportistica che devono consultare grandi volumi di corrispettivi.

Ogni documento restituito contiene le principali informazioni fiscali e gli identificativi necessari per recuperare il dettaglio completo del corrispettivo tramite l'endpoint dedicato.

ESEMPIO RICHIESTA

Per consultare i corrispettivi elettronici è sufficiente effettuare una richiesta al servizio GET /IT-e-receipts. È possibile utilizzare i parametri di ricerca previsti dall'API per filtrare i documenti restituiti.

ESEMPIO RISPOSTA

Se la richiesta viene elaborata correttamente, l'API restituisce l'elenco dei corrispettivi elettronici trovati. Per ogni documento vengono fornite le principali informazioni fiscali, tra cui lo stato, il numero del documento, la data di emissione, gli articoli venduti, gli importi incassati e gli indicatori che specificano se il corrispettivo può essere annullato o utilizzato per un'operazione di reso.

{
  "data": [
    {
      "fiscal_id": "11122211133",
      "type": "sale",
      "cashier_id": null,
      "store_id": "69e1f1335c3954b240083fd4",
      "cr_id": "69e1f1335c3954b240083fd5",
      "status": "ready",
      "created_at": "2026-04-17T15:30:12.000Z",
      "items": [
        {
          "type": "goods",
          "id": 1,
          "quantity": "4.00",
          "description": "Mouse wireless premium",
          "unit_price": "2.00",
          "vat_rate_code": "22.00",
          "simplified_vat_allocation": false,
          "discount": "0.00",
          "surcharge": "0.00",
          "prepaid_or_voucher": false,
          "complimentary": false
        }
      ],
      "invoice_issuing": false,
      "uncollected_dcr_to_ssn": false,
      "discount": "0.00",
      "additional_text": null,
      "cash_payment_amount": "0.00",
      "electronic_payment_amount": "8.00",
      "ticket_restaurant_payment_amount": "0.00",
      "ticket_restaurant_quantity": 0,
      "services_uncollected_amount": "0.00",
      "goods_uncollected_amount": "0.00",
      "id": "69e2520543070c786b0c77c4",
      "document_number": "0001-0003",
      "document_date": "2026-04-17T17:30:12.000Z",
      "total_amount": 8,
      "is_voidable": true,
      "is_returnable": true
    }
  ],
  "success": true,
  "message": "",
  "error": null
}

Gestione dei resi

PATCH /IT-e-receipts/{id}

L'endpoint PATCH /IT-e-receipts/{id} consente di effettuare il reso di uno o più articoli presenti in un corrispettivo elettronico già emesso. L'identificativo del documento originale viene specificato nel percorso della richiesta, mentre gli articoli da restituire e le relative quantità vengono definiti nel payload.

È possibile associare il reso a uno specifico cassiere, punto vendita o registratore di cassa. Se questi parametri non vengono indicati, il sistema utilizza automaticamente il registratore di cassa con cui è stato emesso il documento originale. Per evitare errori, prima di effettuare un reso è consigliabile utilizzare l'endpoint GET /IT-e-receipts/{id}/returnable-items, che restituisce gli articoli ancora disponibili per la restituzione e le relative quantità.

Le quantità indicate vengono automaticamente validate rispetto al documento originale per evitare restituzioni superiori agli importi disponibili.

ESEMPIO RICHIESTA

Per registrare il reso di uno o più articoli è sufficiente effettuare una richiesta al servizio PATCH /IT-e-receipts/{id}, indicando gli articoli da restituire e le relative quantità. Facoltativamente è possibile specificare il registratore di cassa e il cassiere che gestiscono l'operazione.

{
  "cr_id": "69e0ad3456b8f49252094fab",
  "cashier_id": "69d7c469f6d16f5f4003eca6",
  "items": [
    {
      "id": 1,
      "quantity": "2.00"
    }
  ]
}

ESEMPIO RISPOSTA

Se il reso viene registrato correttamente, l'API restituisce un nuovo documento commerciale di tipo return, collegato al corrispettivo elettronico originale tramite il campo parent_receipt_id. In questo modo viene mantenuta la completa tracciabilità dell'operazione senza modificare il documento iniziale.

{
  "data": {
    "fiscal_id": "11122211133",
    "type": "return",
    "cashier_id": null,
    "store_id": "69e1f1335c3954b240083fd4",
    "cr_id": "69e1f1335c3954b240083fd5",
    "status": "ready",
    "created_at": "2026-04-17T15:36:57.000Z",
    "items": [
      {
        "type": "goods",
        "id": 1,
        "quantity": "1.00",
        "description": "Mouse wireless premium",
        "unit_price": "2.00",
        "vat_rate_code": "22.00",
        "simplified_vat_allocation": false,
        "discount": "0.00",
        "surcharge": "0.00",
        "prepaid_or_voucher": false,
        "complimentary": false
      }
    ],
    "id": "69e2539a43070c786b0c77c5",
    "parent_receipt_id": "69e2520543070c786b0c77c4",
    "document_number": "0001-0004",
    "document_date": "2026-04-17T17:36:58.000Z",
    "is_voidable": false,
    "is_returnable": false
  },
  "success": true,
  "message": "",
  "error": null
}

Annullamento di un corrispettivo elettronico

DELETE /IT-e-receipts/{id}

L'endpoint DELETE /IT-e-receipts/{id} permette di annullare un corrispettivo elettronico già emesso. L'operazione non modifica il documento originale, ma genera un nuovo documento di annullamento collegato al corrispettivo iniziale tramite il campo parent_receipt_id, garantendo la completa tracciabilità fiscale dell'operazione.

Facoltativamente è possibile specificare il cassiere, il punto vendita o il registratore di cassa che devono eseguire l'annullamento. Se questi parametri non vengono forniti, il sistema utilizza automaticamente la configurazione associata al documento originale.

Un corrispettivo elettronico può essere annullato solo se risulta ancora annullabile. I documenti già annullati o interamente restituiti non possono essere oggetto di una nuova operazione di annullamento.

ESEMPIO RICHIESTA

Per annullare un corrispettivo elettronico è sufficiente effettuare una richiesta al servizio DELETE /IT-e-receipts/{id}, specificando l'identificativo del documento. Facoltativamente è possibile indicare nel body della richiesta il cassiere, il punto vendita o il registratore di cassa da utilizzare per l'operazione.

DELETE /IT-e-receipts/69e2584a4a218eb38c03c012

ESEMPIO RISPOSTA

Se l'annullamento viene completato correttamente, l'API restituisce un nuovo documento di tipo void, collegato al corrispettivo elettronico originale tramite il campo parent_receipt_id. In questo modo viene preservata la cronologia completa delle operazioni effettuate sul documento commerciale.

{
  "data": {
    "fiscal_id": "11122211133",
    "type": "void",
    "cashier_id": null,
    "store_id": "69e1f1335c3954b240083fd4",
    "cr_id": "69e1f1335c3954b240083fd5",
    "status": "ready",
    "created_at": "2026-04-17T15:57:10.000Z",
    "id": "69e2585782410398e20c4642",
    "parent_receipt_id": "69e2584a4a218eb38c03c012",
    "is_voidable": false,
    "is_returnable": false
  },
  "message": "voided receipt: 69e2584a4a218eb38c03c012",
  "success": true,
  "error": null
}

Gestione dei cassieri

Ogni corrispettivo elettronico può essere associato a un cassiere specifico. Tramite gli endpoint dedicati è possibile creare e gestire i cassieri che operano sui punti vendita, assegnando a ciascuno le proprie credenziali e mantenendo la tracciabilità delle operazioni effettuate.

La gestione dei cassieri risulta particolarmente utile per attività con più operatori o più postazioni di vendita, consentendo di identificare con precisione chi ha emesso ciascun documento commerciale.

POST /IT-cashiers

L'endpoint POST /IT-cashiers permette di creare un nuovo cassiere per il servizio Corrispettivi Elettronici. Ogni cassiere dispone delle proprie credenziali e può essere associato ai corrispettivi elettronici emessi tramite l'API.

ESEMPIO RICHIESTA

Per creare un nuovo cassiere è sufficiente effettuare una richiesta al servizio POST /IT-cashiers, specificando l'indirizzo email, il nome del cassiere e la Partita IVA dell'azienda a cui verrà associato.

{
  "email": "[email protected]",
  "name": "Mario Rossi",
  "fiscal_id": "11122211133"
}

ESEMPIO RISPOSTA

Se la richiesta viene elaborata correttamente, l'API restituisce il nuovo cassiere creato con il relativo identificativo univoco, lo stato di attivazione e le informazioni associate all'azienda.

{
  "data": {
    "id": "69d7c469f6d16f5f4003eca6",
    "email": "[email protected]",
    "name": "Mario Rossi",
    "status": "active",
    "fiscal_id": "11122211133"
  },
  "success": true,
  "message": "Cashier created successfully",
  "error": null
}

Gestione di punti vendita e cassieri

L'API Corrispettivi Elettronici è progettata per adattarsi anche ad attività con più punti vendita e più operatori. Tramite la configurazione iniziale è possibile definire uno o più Store (PEM), associare a ciascuno i relativi registratori di cassa e gestire i cassieri che operano all'interno dell'infrastruttura.

Ogni corrispettivo elettronico può essere associato a uno specifico punto vendita, a un registratore di cassa e, se previsto, al cassiere che ha effettuato l'operazione. Questo consente di mantenere una completa tracciabilità dei documenti commerciali e di semplificare la gestione di reti retail, catene di negozi e attività con più postazioni di vendita.

Gli endpoint dedicati consentono inoltre di gestire le operazioni di manutenzione dei punti vendita, come la riattivazione di uno Store sospeso, la chiusura giornaliera e le comunicazioni previste per le situazioni di emergenza, garantendo il rispetto dei flussi operativi richiesti dal servizio.

Automatizza la gestione dei Corrispettivi Elettronici

L'API Corrispettivi Elettronici permette di integrare in un'unica soluzione l'intero ciclo di vita dei documenti commerciali: dalla configurazione dell'azienda e dei punti vendita, fino all'emissione, alla consultazione, alla gestione di resi e annullamenti.

Grazie al supporto per Store, registratori telematici e cassieri, la soluzione si adatta sia a singoli punti vendita sia a realtà con più sedi operative, garantendo un'integrazione scalabile e conforme ai flussi previsti dall'Agenzia delle Entrate.

Con API REST semplici da integrare e una documentazione completa, puoi automatizzare la gestione dei corrispettivi elettronici all'interno di software gestionali, sistemi POS, ERP e applicazioni retail, riducendo gli interventi manuali e semplificando i processi operativi.