Elektronische Kassenbelege (E-Receipts)

Die API für elektronische Kassenbelege ermöglicht die Erstellung, Übermittlung und Verwaltung elektronischer Kassenbelege gegenüber der italienischen Steuerbehörde über eine einzige Integration. Die Lösung wurde entwickelt, um den gesamten Ausstellungsprozess von Geschäftsbelegen zu automatisieren und die steuerliche Verwaltung für stationäre Verkaufsstellen und Unternehmenssoftware zu vereinfachen.

Mit Openapi können Sie Unternehmen, Betriebsstätten, Stores, elektronische Registrierkassen und Kassierer konfigurieren und so eine vollständige Infrastruktur für die Verwaltung elektronischer Kassenbelege aufbauen. Nach Abschluss der Konfiguration ist jeder Store bereit, Geschäftsbelege auszustellen, Retouren und Stornierungen zu verwalten sowie sämtliche Vorgänge über die API nachzuverfolgen.

Die API unterstützt den gesamten Lebenszyklus elektronischer Kassenbelege – von der Erstkonfiguration über die Ausstellung und Abfrage bis hin zur Verwaltung nachgelagerter Vorgänge – und bietet eine skalierbare Integration, die sich auch für Unternehmen mit mehreren Verkaufsstellen eignet.

Die Lösung eignet sich für Unternehmenssoftware, POS-Systeme, ERP-Plattformen, Retail-Anwendungen sowie jede Software, die die Verwaltung elektronischer Kassenbelege direkt in ihre Geschäftsprozesse integrieren möchte.

Alle Vorgänge werden über eine dedizierte Infrastruktur für elektronische Kassenbelege verwaltet, sodass die gesamte Umgebung über eine einzige API-Integration gesteuert werden kann.

Konfiguration von Unternehmen, Stores und Registrierkassen

POST /IT-configurations

Die Konfiguration ist der erste erforderliche Schritt zur Nutzung der API für elektronische Kassenbelege. Über diesen Endpoint können Sie Ihr Unternehmen registrieren und die gesamte Infrastruktur konfigurieren, die für die Verwaltung von Geschäftsbelegen erforderlich ist.

Während dieses Schritts können Sie den Firmensitz konfigurieren, einen oder mehrere Stores (Verkaufsstellen) anlegen, jedem Store eine oder mehrere elektronische Registrierkassen zuweisen und Callbacks konfigurieren, um automatisch Benachrichtigungen über die von der API ausgeführten Vorgänge zu erhalten.

Jeder Store kann eine oder mehrere elektronische Registrierkassen verwalten, während jeder elektronische Kassenbeleg der Registrierkasse zugeordnet werden kann, die den Geschäftsbeleg ausgestellt hat.

ANFRAGEBEISPIEL

Um Ihr Unternehmen zu konfigurieren, senden Sie eine Anfrage an POST /IT-configurations. Im folgenden Beispiel werden das Unternehmen, sein Firmensitz, ein Store mit zwei elektronischen Registrierkassen sowie die Callbacks für den automatischen Empfang von Statusaktualisierungen konfiguriert.

{
  "fiscal_id": "YourCompanyFiscal_id",
  "name": "Firmenname",
  "email": "[email protected]",
  "receipts": true,
  "customer_invoice": true,
  "supplier_invoice": true,
  "e_receipts": false,
  "legal_storage": false,
  "merchant_address": {
    "street_address": "Hauptstraße",
    "street_number": "10",
    "zip_code": "00100",
    "city": "Rom",
    "province": "RM"
  },
  "stores": [
    {
      "label": "Store Innenstadt",
      "address": {
        "street_address": "Hauptstraße",
        "street_number": "10",
        "zip_code": "00100",
        "city": "Rom",
        "province": "RM"
      },
      "cash_registers": [
        {
          "label": "Registrierkasse 1"
        },
        {
          "label": "Registrierkasse 2"
        }
      ]
    }
  ],
  "receipts_authentication": {
    "taxCode": "FHHWMF96L52D111B",
    "password": "1234567891****d",
    "pin": "1********4"
  },
  "api_configurations": [
    {
      "event": "receipt",
      "callback": {
        "url": "https://your-server.com/123232"
      }
    },
    {
      "event": "customer_invoice",
      "callback": {
        "url": "https://your-server.com/123232"
      }
    },
    {
      "event": "supplier_invoice",
      "callback": {
        "url": "https://your-server.com/123232"
      }
    },
    {
      "event": "receipt-error",
      "callback": {
        "url": "https://your-server.com/error"
      }
    }
  ]
}

ANTWORTBEISPIEL

Nach erfolgreicher Konfiguration gibt die API die Daten des registrierten Unternehmens, die aktivierten Dienste, die Konfiguration der Stores sowie die zugehörigen elektronischen Registrierkassen zurück. Außerdem bestätigt die Antwort, dass die Konfiguration aktiv ist, und liefert die eindeutige Kennung für nachfolgende Verwaltungsvorgänge.

Ausstellung elektronischer Kassenbelege

POST /IT-e-receipts

Der Endpoint POST /IT-e-receipts ermöglicht die Ausstellung eines elektronischen Kassenbelegs für stationäre Verkaufsstellen. Das Dokument wird über den zuvor im Dienst IT-configurations konfigurierten Store (PEM) und die zugehörige elektronische Registrierkasse übermittelt.

Um diesen Dienst nutzen zu können, muss die Option e_receipts in der Unternehmenskonfiguration aktiviert sein. Außerdem muss eine gültige italienische Umsatzsteuer-Identifikationsnummer im Feld fiscal_id angegeben werden und mindestens ein Store mit einer zugeordneten elektronischen Registrierkasse bereits konfiguriert sein.

Bei der Ausstellung des Dokuments können Sie den Kassierer, den Store und die elektronische Registrierkasse angeben, die verwendet werden sollen. Die API überprüft automatisch die Zugehörigkeit der angegebenen Ressourcen und verwendet die Konfiguration des ausgewählten Stores und der entsprechenden Registrierkasse.

Standardmäßig erstellt der Dienst einen Verkaufsbeleg (type: sale). Darüber hinaus werden auch erweiterte Szenarien wie Kaufnachweise, Retouren und Stornierungen über die in der Dokumentation beschriebenen Endpoints und Schemas unterstützt.

ANFRAGEBEISPIEL

Um einen elektronischen Kassenbeleg auszustellen, senden Sie eine Anfrage an POST /IT-e-receipts. Im folgenden Beispiel wird ein Verkaufsbeleg (type: sale) erstellt und einem zuvor konfigurierten Store, einer elektronischen Registrierkasse und einem Kassierer zugeordnet. Das Dokument enthält einen Verkaufsartikel sowie eine elektronische Zahlung in Höhe des Gesamtbetrags des Kassenbelegs.

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

ANTWORTBEISPIEL

Wird die Anfrage erfolgreich verarbeitet, gibt die API den neu erstellten elektronischen Kassenbeleg mit seiner eindeutigen Kennung, der Belegnummer, dem Ausstellungsdatum, dem Verarbeitungsstatus sowie allen steuerlichen Informationen zum Geschäftsbeleg zurück.

{
  "data": {
    "fiscal_id": "11122211133",
    "type": "sale",
    "cashier_id": "69d7c469f6d16f5f4003eca6",
    "store_id": "69ca63ce0f8c187ebf0aa36c",
    "cr_id": "69d8cfbba3ccba0fcc0d0184",
    "status": "ready",
    "created_at": "2026-04-17T15:30:12.000Z",
    "items": [
      {
        "type": "goods",
        "id": 1,
        "quantity": "4.00",
        "description": "Kabellose Premium-Maus",
        "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
      }
    ],
    "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
}

Abrufen elektronischer Kassenbelege

GET /IT-e-receipts

Der Endpoint GET /IT-e-receipts ermöglicht das Abrufen aller über die API ausgestellten elektronischen Kassenbelege. Er bietet einen vollständigen Überblick über die Geschäftsbelege, die an einer oder mehreren Verkaufsstellen erstellt wurden.

Die Ergebnisse können mithilfe der verfügbaren Suchparameter gefiltert werden. Dadurch lassen sich auch große Mengen elektronischer Kassenbelege einfach durchsuchen, überwachen und verwalten – beispielsweise innerhalb von Unternehmenssoftware, ERP-Systemen oder Retail-Plattformen.

Jeder zurückgegebene Beleg enthält die wichtigsten steuerlichen Informationen sowie die erforderlichen Identifikatoren, um die vollständigen Belegdaten abzurufen oder nachfolgende Vorgänge wie Retouren oder Stornierungen durchzuführen.

ANFRAGEBEISPIEL

Um elektronische Kassenbelege abzurufen, senden Sie einfach eine Anfrage an GET /IT-e-receipts. Mithilfe der verfügbaren Suchparameter können Sie die zurückgegebenen Dokumente entsprechend Ihren Anforderungen filtern.

GET /IT-e-receipts

ANTWORTBEISPIEL

Wird die Anfrage erfolgreich verarbeitet, gibt die API eine Liste der gefundenen elektronischen Kassenbelege zurück. Für jeden Beleg werden der Verarbeitungsstatus, die Belegnummer, das Ausstellungsdatum, die verkauften Artikel, Zahlungsinformationen sowie Hinweise darauf zurückgegeben, ob der Beleg noch storniert oder für eine Retoure verwendet werden kann.

{
  "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": "Kabellose Premium-Maus",
          "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
}

Verwaltung von Retouren

PATCH /IT-e-receipts/{id}

Der Endpoint PATCH /IT-e-receipts/{id} ermöglicht die Rückgabe eines oder mehrerer Artikel eines bereits ausgestellten elektronischen Kassenbelegs. Die Kennung des ursprünglichen Dokuments wird im Anfragepfad angegeben, während die zurückzugebenden Artikel und deren Mengen im Anfrage-Body definiert werden.

Eine Retoure kann einem bestimmten Kassierer, Store oder einer elektronischen Registrierkasse zugeordnet werden. Werden diese Parameter nicht angegeben, verwendet das System automatisch die Registrierkasse, mit der der ursprüngliche Kassenbeleg erstellt wurde. Vor der Durchführung einer Retoure können Sie den Endpoint GET /IT-e-receipts/{id}/returnable-items verwenden, um alle noch retournierbaren Artikel sowie deren verfügbare Mengen abzurufen.

Die angegebenen Mengen werden automatisch mit dem ursprünglichen Kassenbeleg abgeglichen, sodass Retouren, die die verfügbare Menge überschreiten, verhindert werden.

ANFRAGEBEISPIEL

Um die Rückgabe eines oder mehrerer Artikel zu registrieren, senden Sie eine Anfrage an PATCH /IT-e-receipts/{id} und geben Sie die zurückzugebenden Artikel sowie deren Mengen an. Optional können Sie auch die elektronische Registrierkasse und den Kassierer angeben, der den Vorgang durchführt.

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

ANTWORTBEISPIEL

Wird die Retoure erfolgreich verarbeitet, erstellt die API einen neuen Geschäftsbeleg vom Typ return, der über das Feld parent_receipt_id mit dem ursprünglichen elektronischen Kassenbeleg verknüpft ist. Dadurch bleibt die vollständige Nachvollziehbarkeit des Vorgangs erhalten, ohne das Originaldokument zu verändern.

{
  "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": "Kabellose Premium-Maus",
        "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
}

Stornierung eines elektronischen Kassenbelegs

DELETE /IT-e-receipts/{id}

Der Endpoint DELETE /IT-e-receipts/{id} ermöglicht die Stornierung eines bereits ausgestellten elektronischen Kassenbelegs. Dabei wird das ursprüngliche Dokument nicht verändert. Stattdessen erstellt das System einen neuen Stornierungsbeleg, der über das Feld parent_receipt_id mit dem Originalbeleg verknüpft wird und so eine vollständige steuerliche Nachvollziehbarkeit gewährleistet.

Optional können Sie den Kassierer, den Store oder die elektronische Registrierkasse angeben, die die Stornierung durchführen soll. Werden diese Parameter nicht übermittelt, verwendet das System automatisch die dem ursprünglichen Beleg zugeordnete Registrierkasse.

Ein elektronischer Kassenbeleg kann nur storniert werden, solange er noch für eine Stornierung berechtigt ist. Bereits stornierte oder vollständig retournierte Belege können nicht erneut storniert werden.

ANFRAGEBEISPIEL

Um einen elektronischen Kassenbeleg zu stornieren, senden Sie eine Anfrage an DELETE /IT-e-receipts/{id} und geben Sie die Kennung des zu stornierenden Dokuments an. Optional können Sie im Request-Body auch den Kassierer, den Store oder die elektronische Registrierkasse angeben, die den Vorgang ausführen soll.

DELETE /IT-e-receipts/69e2584a4a218eb38c03c012

ANTWORTBEISPIEL

Nach erfolgreicher Stornierung gibt die API ein neues Dokument vom Typ void zurück, das über das Feld parent_receipt_id mit dem ursprünglichen elektronischen Kassenbeleg verknüpft ist. Dadurch bleibt der vollständige Verlauf aller am Geschäftsbeleg vorgenommenen Vorgänge erhalten.

{
  "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": "Kassenbeleg storniert: 69e2584a4a218eb38c03c012",
  "success": true,
  "error": null
}

Kassiererverwaltung

Jeder elektronische Kassenbeleg kann einem bestimmten Kassierer zugeordnet werden. Über die entsprechenden Endpoints können Sie Kassierer für Ihre Verkaufsstellen anlegen und verwalten, individuelle Zugangsdaten vergeben und die vollständige Nachvollziehbarkeit jeder Transaktion sicherstellen.

Die Kassiererverwaltung eignet sich insbesondere für Unternehmen mit mehreren Mitarbeitern oder Kassenplätzen, da jederzeit nachvollzogen werden kann, welcher Kassierer den jeweiligen Geschäftsbeleg ausgestellt hat.

POST /IT-cashiers

Der Endpoint POST /IT-cashiers ermöglicht das Anlegen eines neuen Kassierers für den Dienst Elektronische Kassenbelege. Jeder Kassierer verfügt über eigene Zugangsdaten und kann den über die API ausgestellten Kassenbelegen zugeordnet werden.

ANFRAGEBEISPIEL

Um einen neuen Kassierer anzulegen, senden Sie eine Anfrage an POST /IT-cashiers und geben Sie die E-Mail-Adresse, den vollständigen Namen sowie die Umsatzsteuer-Identifikationsnummer des Unternehmens an, dem der Kassierer zugeordnet werden soll.

{
  "email": "[email protected]",
  "name": "Max Mustermann",
  "fiscal_id": "11122211133"
}

ANTWORTBEISPIEL

Wird die Anfrage erfolgreich verarbeitet, gibt die API den neu angelegten Kassierer einschließlich seiner eindeutigen Kennung, seines Aktivierungsstatus sowie der zugehörigen Unternehmensdaten zurück.

{
  "data": {
    "id": "69d7c469f6d16f5f4003eca6",
    "email": "[email protected]",
    "name": "Max Mustermann",
    "status": "active",
    "fiscal_id": "11122211133"
  },
  "success": true,
  "message": "Kassierer erfolgreich erstellt",
  "error": null
}

Verwaltung von Stores und Kassierern

Die API für elektronische Kassenbelege wurde für Unternehmen mit mehreren Verkaufsstellen und mehreren Mitarbeitern entwickelt. Während der Erstkonfiguration können Sie einen oder mehrere Stores anlegen, jedem Store mehrere elektronische Registrierkassen zuordnen und die innerhalb Ihrer Infrastruktur tätigen Kassierer verwalten.

Jeder elektronische Kassenbeleg kann einem bestimmten Store, einer elektronischen Registrierkasse und – sofern erforderlich – dem Kassierer zugeordnet werden, der die Transaktion durchgeführt hat. Dadurch wird eine vollständige Nachvollziehbarkeit der Geschäftsbelege gewährleistet und gleichzeitig die Verwaltung von Filialketten, Unternehmen mit mehreren Standorten und Organisationen mit mehreren Kassenplätzen vereinfacht.

Über die entsprechenden Endpoints können außerdem Wartungsvorgänge für Stores durchgeführt werden, darunter die Reaktivierung eines Stores, tägliche Abschlussprozesse sowie die Kommunikation in Notfallsituationen – stets im Einklang mit den vom Dienst unterstützten Betriebsabläufen.

Automatisieren Sie die Verwaltung elektronischer Kassenbelege

Die API für elektronische Kassenbelege ermöglicht die Verwaltung des gesamten Lebenszyklus elektronischer Kassenbelege über eine einzige Integration – von der Konfiguration des Unternehmens und der Stores bis hin zur Ausstellung, Abfrage, Durchführung von Retouren und Stornierungen.

Dank der Unterstützung von Stores, elektronischen Registrierkassen und Kassierern eignet sich die Lösung sowohl für einzelne Verkaufsstellen als auch für Unternehmen mit mehreren Standorten und bietet eine skalierbare Integration, die den betrieblichen Anforderungen an die Verwaltung elektronischer Kassenbelege in Italien entspricht.

Mit einfach integrierbaren REST-APIs und einer umfassenden Dokumentation können Sie die Verwaltung elektronischer Kassenbelege in Unternehmenssoftware, POS-Systeme, ERP-Plattformen und Retail-Anwendungen integrieren, manuelle Tätigkeiten reduzieren und Ihre Geschäftsprozesse effizienter gestalten.