Invoice

Senden Sie elektronische Belege einfach, schnell und mit hohen Sicherheitsstandards an die italienische Steuerbehörde.

Automatisieren Sie die Übermittlung von Handelsdokumenten in Echtzeit über API.

All das Wissen, das Sie benötigen

Hier finden Sie einige Ratschläge, die Sie berücksichtigen sollten, um sich dieser API zu nähern. Wenn Sie möchten, bieten wir Code-Beispiele, OAS3-Dokumentation, die Möglichkeit, die API live über Swagger UI auszuprobieren oder die gesamte Sammlung in Postman zu importieren. Wir bieten auch eine Sandbox-Umgebung an, in der Sie kostenlos mit allen Arten von Anfragen experimentieren können.

Nützliche Tipps für den Einstieg Invoice

Holen Sie sich das Token im entsprechenden Abschnitt, bevor Sie beginnen.

Verwenden Sie das Online-Tool oder generieren Sie es über die API. Legen Sie das Ablaufdatum, einen nützlichen Namen fest und fügen Sie jetzt eine Vielzahl von Scopes hinzu, um die möglichen Aktionen Ihres Tokens zu begrenzen.

Unternehmenskonfiguration

Neue Konfiguration erstellen
POST /IT-configurations
Dieser Endpunkt ermöglicht die Erstellung einer neuen Unternehmenskonfiguration. Es können Anmeldeinformationen und Callback-URLs für den Empfang von Belegbenachrichtigungen hinzugefügt werden.

Konfigurationen abrufen
GET /IT-configurations
Dieser Endpunkt gibt eine Liste der registrierten Konfigurationen zurück.

Eine bestehende Konfiguration aktualisieren
PATCH /IT-configurations/{fiscal_id}
Dieser Endpunkt ermöglicht das Aktualisieren der Anmeldeinformationen oder die Änderung der Callback-URLs einer vorhandenen Konfiguration.

Eine Konfiguration löschen
DELETE /IT-configurations/{fiscal_id}
Dieser Endpunkt ermöglicht das Löschen einer Konfiguration. Hinweis: Wenn bereits Belege mit dieser Konfiguration gesendet wurden, ist eine Löschung nicht mehr möglich.

Belegverwaltung

Nutzen Sie die folgenden Endpunkte zur Verwaltung elektronischer Belege:

Neuen Beleg erstellen
POST /IT-receipts
Dieser Endpunkt ermöglicht das Senden eines neuen elektronischen Belegs. Eine eindeutige id wird generiert, und eine Benachrichtigung wird an die konfigurierte Callback-URL gesendet.

Rückgabe registrieren
PATCH /IT-receipts/{id}
Wenn ein Kunde ein Produkt zurückgibt, kann mit diesem Endpunkt der ursprüngliche Beleg aktualisiert und eine Rückgabe registriert werden.

Beleg stornieren
DELETE /IT-receipts/{id}
Dieser Endpunkt ermöglicht die Stornierung eines zuvor gesendeten Belegs. Eine Stornierungsbenachrichtigung wird an die konfigurierte Callback-URL gesendet.

Belege abrufen
GET /IT-receipts
Dieser Endpunkt gibt eine Liste der registrierten Belege zurück, mit Filteroptionen für Datum, Betrag usw.

Invoice (1.0.0)

API für die Verwaltung von Rechnungskonfigurationen und digitalen Quittungen in Übereinstimmung mit den Steuervorschriften. Dieser Dienst ermöglicht es Unternehmen, ihre Rechnungseinstellungen zu konfigurieren und Belege zu verwalten, um die Einhaltung der Standards der italienischen Steuerbehörde (Agenzia delle Entrate) für die elektronische Rechnungsstellung (Fatturazione Elettronica) und die digitale Belegübermittlung (Scontrino Elettronico) zu gewährleisten. Es unterstützt den sicheren Datenaustausch, die Übermittlung von Quittungen in Echtzeit und die Aktualisierung der Konfiguration für die steuerlichen Berichtsanforderungen.

WICHTIG: Bitte beachten Sie, dass Sie zwischen 23:55 und 00:00 Uhr (italienische Zeitzone) keine Belege an die italienische Steuerbehörde (Agenzia delle Entrate) senden können. Aus diesem Grund werden alle Quittungen, die in diesem Zeitraum gesendet werden, zum ersten verfügbaren Zeitpunkt gesendet, d.h. in den ersten Minuten des neuen Tages.

NB: Es ist notwendig, den in der Konfiguration unter receipts_authentication-taxCode eingetragenen Steuercode für den Versand von Quittungen zu aktivieren. Folgen Sie dem unter diesem Link beschriebenen Verfahren.

IT-configuration

Verwalten von Unternehmenskonfigurationen.

Rufen Sie alle IT-Konfigurationen ab.

Abrufen aller mit dem Benutzer verbundenen IT-Konfigurationen. Dieser Endpunkt gibt eine Liste von Konfigurationen zurück, einschließlich steuerlicher Details und API-Benachrichtigungseinstellungen. Er ermöglicht es Unternehmen, ihre Integration mit der Steuerbehörde zu verwalten und quittungsbezogene Ereignisse zu überwachen.

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array of objects (ITConfigurationResponse)

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

Erstellen Sie eine neue IT-Konfiguration.

Die IT-Konfiguration ist ein Werkzeug, mit dem Sie Unternehmensdaten für Ihr eigenes Unternehmen festlegen und verwalten können. Sie fungiert als eine Einheit, die ein von Ihrem Konto verwaltetes Unternehmen darstellt. Über diese Konfiguration können verschiedene Einstellungen angepasst werden

WICHTIG: Um Benachrichtigungen zu erhalten, müssen Sie die api_configurations einfügen und das Ereignis wie in den Schemata angegeben einstellen. Es wird immer möglich sein, die Daten mit der PATCH IT-Konfiguration zu aktualisieren

Für den Versand von Quittungen muss die Option receipts auf true gesetzt werden.

Standardmäßig wird alles auf false gesetzt.

Es wird möglich sein, bis zu 10 Unternehmen pro Tag kostenlos zu konfigurieren, danach wird der angegebene Preis angewendet

Authorizations:
bearerAuth
Request Body schema: application/json
fiscal_id
required
string

Die eindeutige steuerliche Kennung (MwSt.-Nummer oder Steuernummer) des bei der Agenzia delle Entrate registrierten Unternehmens.

name
required
string

Der Name des Unternehmens oder der Körperschaft, der mit der Steuer-ID verbunden ist.

email
required
string <email>

Die E-Mail-Adresse, die für Kommunikation und Benachrichtigungen verwendet wird. Kann nicht mehr geändert werden, nachdem die Konfiguration erstellt wurde.

receipts
boolean

Gibt an, ob das System digitale Quittungen verarbeiten soll.

object

Für die Übermittlung der digitalen Quittung erforderliche Authentifizierungsdaten.

Array of objects non-empty

Konfiguration von ereignisbasierten Callbacks für den Empfang von Benachrichtigungen.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string or null

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Abrufen einer einzelnen IT-Konfiguration nach fiscal_id.

Dieser Endpunkt liefert Details zu einer individuellen Konfiguration, einschließlich Steuerdetails und API-Benachrichtigungseinstellungen. Er ermöglicht es Unternehmen, ihre Integration mit der Steuerbehörde zu verwalten und Ereignisse im Zusammenhang mit Quittungen zu überwachen

Authorizations:
bearerAuth
path Parameters
fiscal_id
required
string

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string or null

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations/%7Bfiscal_id%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Aktualisierung einer bestehenden IT-Konfiguration.

Dieser Dienst ermöglicht es Ihnen, Authentifizierungsdaten zu ändern oder zu aktualisieren, falls sie abgelaufen sind. Sie können auch die API-Konfigurationen aktualisieren. Wenn Sie für ein bestimmtes Ereignis keine Benachrichtigungen mehr erhalten möchten, setzen Sie den "Callback" einfach auf "null".

NB: Die Anmeldedaten in der receipts_authentication müssen alle 90 Tage aktualisiert werden (für die Agenzia delle entrate).

Authorizations:
bearerAuth
path Parameters
fiscal_id
required
string
Request Body schema: application/json
receipts
boolean

Gibt an, ob das System digitale Quittungen verarbeiten soll.

object

Für die Übermittlung der digitalen Quittung erforderliche Authentifizierungsdaten.

Array of objects non-empty

Konfiguration von ereignisbasierten Callbacks für den Empfang von Benachrichtigungen.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string or null

Request samples

Content type
application/json
{
  • "receipts": true,
  • "receipts_authentication": {
    },
  • "api_configurations": []
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Löschen einer IT-Konfiguration nach fiscal_id.

Dieser Dienst ermöglicht es Ihnen, die Konfiguration zu löschen.

Hinweis: Die Konfiguration kann nur gelöscht werden, wenn keine Quittungen gesendet wurden. Quittungen können über den Endpunkt POST /IT-receipts gesendet werden. Sobald Quittungen gesendet wurden, kann die Konfiguration nicht mehr gelöscht werden.

Authorizations:
bearerAuth
path Parameters
fiscal_id
required
string

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations/%7Bfiscal_id%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": "null",
  • "success": true,
  • "message": "Deleted configuration for id: YourCompanyFiscal_id",
  • "error": null
}

IT-receipt

Bearbeiten Sie die Quittungen.

Rufen Sie alle IT-Belege ab.

Dieser Endpunkt ruft eine Liste von IT-Belege ab und ermöglicht die Filterung anhand verschiedener Parameter. Benutzer können die Ergebnisse nach fiscal_id, document_number, status, type, created_at, document_date und parent_receipt_id filtern.

Zu den Paginierungsoptionen gehören "Skip" (Überspringen), um die Anzahl der auszulassenden Datensätze festzulegen, und "Limit" (Begrenzung), um die maximale Anzahl der zurückgegebenen Datensätze zu definieren (auf 100 begrenzt).

fiscal_id, status und type unterstützen mehrere Werte, indem sie durch ein Komma getrennt werden (z. B. fiscal_id_1,fiscal_id_2).

status gültige Werte: neu, erneut versuchen, eingereicht, bereit, fehlgeschlagen, ungültig.

type gültige Werte: sale, return, void.

created_at und document_date müssen dem Format JJJJ-MM-TT entsprechen.

Dieser Endpunkt gibt eine strukturierte JSON-Antwort mit den entsprechenden Quittungen zurück.

Authorizations:
bearerAuth
query Parameters
fiscal_id
string

Quittungen nach Steuer-ID filtern.

document_number
string

Quittungen nach Belegnummer filtern.

status
Array of strings
Items Enum: "new" "retry" "submitted" "ready" "failed" "voided"

Eingänge nach Status filtern. Es können mehrere Werte angegeben werden, die durch Kommas getrennt sind.

type
Array of strings
Items Enum: "sale" "return" "void"

Quittungen nach Typ filtern. Es können mehrere Werte angegeben werden, die durch Kommas getrennt sind.

created_at
string <date>

Eingänge nach Erstellungsdatum filtern (Format JJJJ-MM-TT).

document_date
string <date>

Quittungen nach Belegdatum filtern (Format JJJJ-MM-TT).

parent_receipt_id
string

Quittungen nach übergeordneter Quittungs-ID filtern.

skip
integer >= 0

Anzahl der zu überspringenden Datensätze für die Paginierung.

limit
integer [ 1 .. 100 ]

Anzahl der zurückzugebenden Datensätze (maximal 100).

Responses

Response Schema: application/json
Array of objects (ResponseReturnReceipt)

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts?fiscal_id=SOME_STRING_VALUE&document_number=SOME_STRING_VALUE&status=SOME_ARRAY_VALUE&type=SOME_ARRAY_VALUE&created_at=SOME_STRING_VALUE&document_date=SOME_STRING_VALUE&parent_receipt_id=SOME_STRING_VALUE&skip=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

Erstellen Sie einen neuen Bon.

Dieser Dienst ermöglicht es Ihnen, eine intelligente elektronische Quittung für einen Online-Verkauf zu erstellen. Die intelligente Quittung ersetzt die Ausstellung einer Quittung durch eine Telekasse und ist ideal für Online-Transaktionen.

Im Gegensatz zu einer e-invoice B2C benötigt die Smart Electronic Receipt keine Steuernummer des Kunden (codice fiscale). Sie interagiert direkt mit dem staatlichen Steuerportal (cassetto fiscale), um die Quittung zu erstellen und zu speichern, und fungiert als Stellvertreter für den Benutzer.

Wichtig: Bevor Sie diesen Dienst nutzen, müssen Sie eine IT-Konfiguration einrichten, die die "Partita IVA" darstellt, die die Quittungen versendet. Stellen Sie sicher, dass das Feld "Quittungen: true" in der IT-Konfigurationsanforderung enthalten ist.

Sandbox-Umgebung: Die Sandbox simuliert die Kommunikation mit dem Portal der Steuerbehörde. In dieser Umgebung werden Smart Receipt Identifikatoren simuliert. Echte Anmeldeinformationen für die IT-Konfiguration des Absenders werden in der Sandbox-Umgebung nicht benötigt, in der Produktionsumgebung sind sie jedoch erforderlich.

NB: Es ist wichtig, die folgenden Ereignisse für die Callbacks zu setzen:

  • Receipt: Dieses Ereignis wird ausgelöst, wenn eine neue Quittung eingereicht wird und bereit ist
  • quittung-Beglaubigungsnachweise": Dieses Ereignis wird ausgelöst, wenn es eine Aktualisierung der Anmeldeinformationen gibt
  • receipt-retry:Dieses Ereignis wird ausgelöst, wenn die Kommunikation mit dem Portal der Steuerbehörde fehlgeschlagen ist und wir erneut versuchen, die Quittung zu senden
  • receipt-error Dieses Ereignis wird ausgelöst, wenn das Portal der Steuerbehörde einen Fehler meldet
  • appointee Dieses Ereignis wird ausgelöst, wenn der Prozess der Erteilung einer Ernennung für intelligente Quittungen erfolgreich war

Dies liegt daran, dass die Belegdetails je nach Ereignistyp aktualisiert werden.

Bevor ein Dokument an das Portal der Steuerbehörde gesendet wird, führt OpenaApi einige Prüfungen der gesendeten Daten durch. Wenn etwas mit den gesendeten Daten nicht in Ordnung ist

Authorizations:
bearerAuth
Request Body schema: application/json
fiscal_id
required
string

Die Umsatzsteuer-Identifikationsnummer des Unternehmens, das die Quittung ausstellt, ohne die Ländervorwahl.

required
Array of objects

Liste der Posten auf dem Bon.

invoice_issuing
boolean

Kennzeichen, das angibt, ob eine Rechnung ausgestellt werden soll.

services_uncollected_amount
number

Nicht eingezogener Betrag in EUR für Dienstleistungen.

goods_uncollected_amount
number

Nicht abgeholter Betrag in EUR für gelieferte Waren.

electronic_payment_amount
number

Elektronisch gezahlter Betrag in EUR.

ticket_restaurant_payment_amount
number

Mit dem Ticket-Restaurant bezahlter Betrag in EUR.

ticket_restaurant_quantity
integer

Anzahl der verwendeten Restaurantgutscheine.

discount
number

Der Rabatt wird zum Zeitpunkt der Zahlung angewandt, ändert aber nicht die Steuerbemessungsgrundlage.

lottery_code
string

Lotteriecode für den Kunden zur Teilnahme an der Lotterie "Lotteria degli scontrini". Der "lottery_code" muss aus 8 alphanumerischen Zeichen bestehen. Der Lotteriecode kann nicht verwendet werden, wenn der Gesamtbetrag unter 1,00 EUR liegt oder wenn die Zahlung nicht vollständig elektronisch erfolgt ist

linked_receipt
string

Verweis auf einen verknüpften Beleg, falls zutreffend.

cash_payment_amount
required
number

In bar gezahlter Betrag in EUR.

tags
Array of objects

Sie können Details für Ihre Quittung einfügen.

Responses

Response Schema: application/json
object
success
boolean

Zeigt an, ob der Vorgang erfolgreich war.

message
string

Zusätzliche Meldung im Zusammenhang mit dem Vorgang.

error
string or null

Fehlermeldung, falls zutreffend.

Callbacks

Request samples

Content type
application/json
{
  • "fiscal_id": "YourCompanyFiscal_id",
  • "items": [
    ],
  • "invoice_issuing": false,
  • "services_uncollected_amount": 0,
  • "goods_uncollected_amount": 0,
  • "electronic_payment_amount": 0,
  • "ticket_restaurant_payment_amount": 0,
  • "ticket_restaurant_quantity": 0,
  • "discount": 0,
  • "lottery_code": "1a3v5g7f",
  • "linked_receipt": "string",
  • "cash_payment_amount": 4.5,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Callback payload samples

Callback
POST: {your_url}
Content type
application/json

Im Callback werden die verschiedenen Typen und Status der Quittung zurückgegeben. Dies ist die Antwort, wenn die Quittung erfolgreich ausgestellt wurde und bereit ist.

{
  • "data": {
    }
}

Abruf eines einzelnen Belegs nach ID.

Ruft die Details einer einzelnen Quittung anhand ihrer eindeutigen Kennung ab. Die Quittungs-ID muss im Abfragepfad angegeben werden.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 679cd95***************23

Responses

Response Schema: application/json
object

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts/%7Bid%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    }
}

Einen oder mehrere Artikel von einem Bon zurückgeben.

Dieser Endpunkt ermöglicht die Rückgabe eines oder mehrerer Artikel aus einem bestimmten Beleg. Die Beleg-ID wird im Pfad angegeben, während die zurückzugebenden Artikel im Anfragetext mit ihren jeweiligen IDs und Mengen angegeben werden.

NB: Die Antwort dieses Endpunkts ist ein neuer Beleg, der mit dem vorherigen Beleg verknüpft ist. Es wird ein neuer Schlüssel, parent_receipt_id, gesetzt, der mit der ID des Belegs gefüllt wird, von dem die Rückgabe erfolgt.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 679c***6d00d0***b23

Eindeutiger Bezeichner des zu aktualisierenden Belegs.

Request Body schema: application/json
Array of objects

Liste der zurückzugebenden Gegenstände.

Responses

Response Schema: application/json
object

Callbacks

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Callback payload samples

Callback
POST: postReceiptCallback
Content type
application/json
Example

Im Callback werden die verschiedenen Typen und Status der Quittung zurückgegeben. Dies ist die Antwort, wenn die Quittung erfolgreich ausgestellt wurde und bereit ist.

{
  • "data": {
    },
  • "custom": null
}

Löschen Sie einen Beleg nach ID.

Dieser Endpunkt ermöglicht die Stornierung eines Bons innerhalb von 24 Stunden nach dessen Einreichung. Das System erzeugt einen neuen stornierten Beleg, der mit dem ursprünglichen Beleg über den Parameter parent_receipt_id verknüpft ist.

Der stornierte Beleg spiegelt die Stornierung der ursprünglichen Transaktion wider, wobei die Rückverfolgbarkeit erhalten bleibt.

Bei Erfolg enthält die Antwort die Details des neu erstellten ungültigen Belegs.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 6a9**************d077b23

Responses

Response Schema: application/json
object
message
string

Bestätigungsmeldung für den entwerteten Bon.

success
boolean

Zeigt an, ob der Vorgang des Ungültigmachens erfolgreich war.

error
string or null

Fehlermeldung im Falle eines Fehlers, null bei Erfolg.

Callbacks

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts/%7Bid%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "voided receipt: 6a9**************d077b23",
  • "success": true,
  • "error": "nulll"
}

Callback payload samples

Callback
POST: postReceiptCallback
Content type
application/json
Example

Im Callback werden die verschiedenen Typen und Status der Quittung zurückgegeben. Dies ist die Antwort, wenn die Quittung erfolgreich entwertet wurde.

{
  • "data": {
    },
  • "custom": null
}