Schrittweise Integration

⚠️ Sie sehen die Dokumentation für API-Version 2026-02-03. Die neueste Version ist 2026-05-04. Die neue API-Version bringt keine Änderungen an der italienischen Integration. Sie fügt jedoch die SIGN PT-Unterstützung hinzu, sodass Teams, die eine Expansion nach Portugal planen, dieselbe Integration wiederverwenden können, die bereits für Italien eingerichtet ist.

Dieser Leitfaden führt Sie durch den vollständigen Prozess der Integration der fiskaly SIGN IT API für die italienische Steuerkonformität mithilfe einer Kombination aus dem fiskaly HUB und API-Anfragen. Am Ende verfügen Sie über ein vollständig funktionierendes System, bei dem Datensätze an die Agenzia delle Entrate (AdE) übermittelt werden.

Integrationsablauf

Das nachstehende Diagramm veranschaulicht den Arbeitsablauf und hebt die wesentlichen Schritte hervor, die für eine erfolgreiche Integration erforderlich sind. Jede Kachel verweist direkt auf den entsprechenden Einrichtungsschritt weiter unten.

📘Wichtig

Die gelb markierten Schritte müssen direkt im HUB ausgeführt werden, während die übrigen Schritte über die API abgewickelt werden müssen. Die Durchführung jeder Aktion im richtigen Kontext ist ein wichtiger Schritt auf dem Weg zu einer erfolgreichen Integration.

Voraussetzungen

📘Bevor Sie beginnen

Sie benötigen ein Tool zur Durchführung von HTTP-Anfragen — beispielsweise cURL (Kommandozeile), Postman oder Ihren eigenen Anwendungscode. Grundlegende Kenntnisse über REST-APIs und Authentifizierungsabläufe werden empfohlen.

Sie können auch unsere Postman-Sammlung für SIGN IT herunterladen, die vorgefertigte Anfragen für jeden Schritt in diesem Leitfaden enthält.

Schrittweise Einrichtung

Im HUB registrieren
Beginnen Sie mit der Registrierung im fiskaly HUB.
Weitere Hinweise zum Einstieg finden Sie in unserem Bereich HUB - Erste Schritte.
Account & Organisation GROUP erstellen
Die Erstellung eines fiskaly-Accounts ist der erste Schritt, danach können Sie mit der Einrichtung der ersten Organisationsstruktur für Ihr Unternehmen und der Generierung Ihres API Keys fortfahren.
Der Account repräsentiert den POS-Anbieter oder einen Händler, der sein eigenes POS-System betreibt. Er ist die übergeordnete Organisation in der Struktur.
Nach der Erstellung Ihres fiskaly-Accounts werden Sie zur Organisationsauswahl weitergeleitet, wo Sie Ihre Group erstellen können. Eine Group ist eine Zwischenebene innerhalb eines Accounts, die Ihnen hilft, mehrere Units in logische Cluster zu organisieren.
API Key erstellen
Im nächsten Schritt generieren Sie einen API Key für Ihre Organisation über den HUB innerhalb Ihrer Group.
Sie erhalten einen API Key und ein API-Secret. Bewahren Sie diese sicher auf — Sie benötigen sie zur Authentifizierung in der SIGN IT API und zur Erstellung Ihrer Organisation(en) vom Typ UNIT (Schritt 5). Das API-Secret wird nur einmal angezeigt. Stellen Sie sicher, dass Sie es sicher speichern, bevor Sie den Dialog schließen.
💡TEST- vs. LIVE-Umgebungen
Mit API Keys, die in der TEST-Umgebung generiert wurden (https://test.api.fiskaly.com), werden TEST-Ressourcen erstellt, während solche aus der LIVE-Umgebung (https://live.api.fiskaly.com) LIVE-Ressourcen erstellen. Weitere Details finden Sie in unserem Artikel über TEST- und LIVE-Umgebungen.

Token erstellen
Ab diesem Schritt verwenden Sie die SIGN IT API.
Rufen Sie den Endpunkt createToken mit dem API Key und Secret aus Schritt 3 auf, um ein bearer-Token zu erhalten. Fügen Sie dieses Token in den Authorization-Header der Schritte 5 und 6 ein.
curl -X POST https://test.api.fiskaly.com/tokens \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -d '{ "content": { "type": "API_KEY", "key": "your_api_key", "secret": "your_api_secret" } }'
Beispielantwort (200 OK)
{ "content": { "id": "6f1c5c9e-3d9c-4f8c-9f20-7de8f3a91b11", "authentication": { "type": "JWT", "bearer": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_at": "2026-03-02T12:00:00Z" }, "organization": { "id": "b7b6f971-5a3c-4e1e-9f58-2f2a8457bb2d" }, "subject": { "id": "2d4a0c2a-c2c9-4e3b-a0e8-b8f7e70d6f33" } } }

Organisation UNIT erstellen

Erstellen Sie eine Organisation vom Typ UNIT über den Endpunkt createOrganization. Eine UNIT repräsentiert eine einzelne juristische Person (Händler). Sie müssen für jede Steuerpflichtigenrepräsentation, die Sie verwalten, eine Organisation UNIT erstellen.

Durch die Verwendung des in Schritt 4 generierten bearer-Tokens mit dem für Ihre Group erstellten API Key und Secret wird sichergestellt, dass die UNIT in der Hierarchie korrekt unter dieser Group verschachtelt ist.

curl -X POST https://test.api.fiskaly.com/organizations \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{
    "content": {
      "type": "UNIT",
      "name": "My Retail Store"
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/organizations",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "UNIT",
        name: "My Retail Store",
      },
    }),
  }
);

const organization = await response.json();
const organizationId = organization.id;

Beispielantwort (201 Created)

{
  "content": {
    "id": "9a746f13-0ef7-4a0f-a7df-8e52089c5f3a",
    "state": "ENABLED",
    "type": "UNIT",
    "name": "My Retail Store",
    "organization": {
      "id": "d4c7b3d1-71f6-45d6-a289-4adf5d54b9c1"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Subject (API Key) erstellen

Erstellen Sie ein Subject vom Typ API_KEY für die Organisation UNIT über den Endpunkt createSubject.

Um das Subject (API Key) mit Ihrer UNIT zu verknüpfen, fügen Sie den Header X-Scope-Identifier mit der id der Organisation UNIT in Ihre Anfrage ein.

curl -X POST https://test.api.fiskaly.com/subjects \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Scope-Identifier: ${ORGANIZATION_ID}" \
  -d '{
    "content": {
      "type": "API_KEY",
      "name": "my-api-key-03"
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/subjects",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${accessToken}`,
      "X-Scope-Identifier": organizationId,
    },
    body: JSON.stringify({
      content: {
        type: "API_KEY",
        name: "my-api-key-03",
      },
    }),
  }
);

const subject = await response.json();
// Save the returned key and secret for the next step

Beispielantwort (201 Created)

{
  "content": {
    "id": "2d4a0c2a-c2c9-4e3b-a0e8-b8f7e70d6f33",
    "state": "ENABLED",
    "type": "API_KEY",
    "name": "my-api-key-03",
    "credentials": {
      "api_key": "fsk_unit_abc123",
      "api_secret": "secret_only_shown_once"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Token erstellen

Erstellen Sie ein Token mit dem gerade generierten Subject API Key und Secret. Dieses bearer-Token wird für alle nachfolgenden Schritte verwendet, um Ressourcen innerhalb der entsprechenden Organisation UNIT zu erstellen.

curl -X POST https://test.api.fiskaly.com/tokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -d '{
    "content": {
      "type": "API_KEY",
      "key": "subject_api_key",
      "secret": "subject_api_secret"
    }
  }'

const tokenResponse = await fetch(
  "https://test.api.fiskaly.com/tokens",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
    },
    body: JSON.stringify({
      content: {
        type: "API_KEY",
        key: "subject_api_key",
        secret: "subject_api_secret",
      },
    }),
  }
);

const { access_token: unitToken } = await tokenResponse.json();

Beispielantwort (200 OK)

{
  "content": {
    "id": "3a5b4c61-2e8d-4a9d-9ac1-6df5a4e9138d",
    "authentication": {
      "type": "JWT",
      "bearer": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expires_at": "2026-03-02T12:00:00Z"
    },
    "organization": {
      "id": "9a746f13-0ef7-4a0f-a7df-8e52089c5f3a"
    },
    "subject": {
      "id": "2d4a0c2a-c2c9-4e3b-a0e8-b8f7e70d6f33"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Steuerpflichtigen erstellen

Nun sind Sie bereit, die für die Fiskalisierung in Italien erforderlichen operativen Teile zu erstellen.

Verwenden Sie den Endpunkt createTaxpayer, um Steuerpflichtigendaten zur zuvor erstellten Organisation UNIT hinzuzufügen:

Setzen Sie den Steuerpflichtigen als Typ COMPANY (juristische Person) oder INDIVIDUAL (natürliche Person). In beiden Fällen müssen name und address angegeben werden.
Innerhalb der italienischen fiscalization-Informationen müssen folgende Steuerpflichtigenangaben bereitgestellt werden:
- tax_id_number: Italienischer Steuercode (Codice fiscale) des Unternehmens
- vat_id_number: Italienische Umsatzsteuer-Identifikationsnummer (Partita IVA) des Unternehmens
- credentials: PIN, Passwort und Steueridentifikationsnummer des Fisconline-Benutzers, der für den Zugriff auf die Dienste der AdE erforderlich ist

curl -X POST https://test.api.fiskaly.com/taxpayers \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "type": "COMPANY",
      "name": {
        "legal": "La Pizzeria di Mario S.r.l.",
        "trade": "La Pizzeria di Mario"
      },
      "address": {
        "line": {
          "type": "STREET_NUMBER",
          "street": "Via Roma",
          "number": "123"
        },
        "code": "00100",
        "city": "Rome",
        "country": "IT"
      },
      "fiscalization": {
        "type": "IT",
        "tax_id_number": "12345678901",
        "vat_id_number": "12345678901",
        "credentials": {
          "type": "FISCONLINE",
          "pin": "1234567890",
          "password": "MySecurePassword123",
          "tax_id_number": "RSSMRA85M01H501Z"
        }
      }
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/taxpayers",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "COMPANY",
        name: {
          legal: "La Pizzeria di Mario S.r.l.",
          trade: "La Pizzeria di Mario",
        },
        address: {
          line: {
            type: "STREET_NUMBER",
            street: "Via Roma",
            number: "123",
          },
          code: "00100",
          city: "Rome",
          country: "IT",
        },
        fiscalization: {
          type: "IT",
          tax_id_number: "12345678901",
          vat_id_number: "12345678901",
          credentials: {
            type: "FISCONLINE",
            pin: "1234567890",
            password: "MySecurePassword123",
            tax_id_number: "RSSMRA85M01H501Z",
          },
        },
      },
    }),
  }
);

const taxpayer = await response.json();
const taxpayerId = taxpayer.id;

Beispielantwort (201 Created)

{
  "content": {
    "address": {
      "city": "Rome",
      "code": "00100",
      "country": "IT",
      "line": {
        "number": "123",
        "street": "Via Roma",
        "type": "STREET_NUMBER"
      }
    },
    "country": "Italy",
    "created_at": "2026-03-05T14:58:05.729928Z",
    "fiscalization": {
      "credentials": {
        "password": "ccf9ac1c",
        "pin": "c775e7b7",
        "tax_id_number": "RSSMRA85M01H501Z",
        "type": "FISCONLINE"
      },
      "tax_id_number": "12345678901",
      "type": "IT",
      "vat_id_number": "12345678901"
    },
    "id": "019cbe81-8721-7e27-99d9-1bb4a267ba56",
    "locations": [
      {
        "description": "Head office location.",
        "type": "HEAD_OFFICE"
      },
      {
        "description": "Branch location.",
        "type": "BRANCH"
      }
    ],
    "mode": "INACTIVE",
    "name": {
      "legal": "La Pizzeria di Mario S.r.l.",
      "trade": "La Pizzeria di Mario"
    },
    "state": "ACQUIRED",
    "type": "COMPANY",
    "updated_at": "2026-03-05T14:58:05.729928Z",
    "vat_number": "IT12345678901"
  }
}

Sobald ein Steuerpflichtiger erstellt wurde, wird sein state standardmäßig auf ACQUIRED gesetzt. Um ihn vollständig funktionsfähig zu machen, aktualisieren Sie den Status auf COMMISSIONED über den Endpunkt updateTaxpayer:

curl -X PATCH "https://test.api.fiskaly.com/taxpayers/${TAXPAYER_ID}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "state": "COMMISSIONED"
    }
  }'

await fetch(
  `https://test.api.fiskaly.com/taxpayers/${taxpayerId}`,
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        state: "COMMISSIONED",
      },
    }),
  }
);

Beispielantwort (200 OK)

{
  "content": {
    "address": {
      "city": "Rome",
      "code": "00100",
      "country": "IT",
      "line": {
        "number": "123",
        "street": "Via Roma",
        "type": "STREET_NUMBER"
      }
    },
    "country": "Italy",
    "created_at": "2026-03-05T14:58:05.729928Z",
    "fiscalization": {
      "credentials": {
        "password": "ccf9ac1c",
        "pin": "c775e7b7",
        "tax_id_number": "RSSMRA85M01H501Z",
        "type": "FISCONLINE"
      },
      "tax_id_number": "12345678901",
      "type": "IT",
      "vat_id_number": "12345678901"
    },
    "id": "019cbe81-8721-7e27-99d9-1bb4a267ba56",
    "locations": [
      {
        "description": "Head office location.",
        "type": "HEAD_OFFICE"
      },
      {
        "description": "Branch location.",
        "type": "BRANCH"
      }
    ],
    "mode": "OPERATIVE",
    "name": {
      "legal": "La Pizzeria di Mario S.r.l.",
      "trade": "La Pizzeria di Mario"
    },
    "state": "COMMISSIONED",
    "type": "COMPANY",
    "updated_at": "2026-03-05T15:02:41.223565Z",
    "vat_number": "IT12345678901"
  }
}

📘Note

Nur Fisconline-Zugangsdaten sind für die Nutzung von SIGN IT lite gültig. Der Steuerpflichtige muss sich manuell erstmalig im Webportal der Steuerbehörde anmelden, um sicherzustellen, dass die Zugangsdaten ordnungsgemäß funktionieren und um die bereitgestellten Nutzungsbedingungen und zusätzlichen Klauseln zu akzeptieren.

⚠️Erneuerung der Zugangsdaten erforderlich

Fisconline-Zugangsdaten laufen alle 90 Tage im AdE-Portal ab, wir empfehlen jedoch eine Erneuerung alle 60 Tage als Best Practice. Erfahren Sie wie in diesem Artikel: SIGN IT - How to update the FISCONLINE credentials

Weitere Informationen finden Sie in unserem Abschnitt Zugangsdaten.

Einen detaillierten Händlerleitfaden zur Beantragung von Fisconline-Zugangsdaten erhalten Sie beim Kontakt zu unserem Vertriebsteam.

Standort erstellen

Für jeden operativen Geschäftsstandort müssen Sie einen Standort vom Typ BRANCH über den Endpunkt createLocation erstellen.

curl -X POST https://test.api.fiskaly.com/locations \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "type": "BRANCH",
      "taxpayer": {
        "id": "your_taxpayer_id"
      },
      "name": "Roma Centro Branch",
      "address": {
        "line": {
          "type": "STREET_NUMBER",
          "street": "Via Roma",
          "number": "1"
        },
        "code": "00100",
        "city": "Roma",
        "country": "IT"
      }
    },
    "metadata": {
      "store_code": "STORE001"
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/locations",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "BRANCH",
        taxpayer: {
          id: taxpayerId,
        },
        name: "Roma Centro Branch",
        address: {
          street: "Via Roma 1",
          zip: "00100",
          city: "Roma",
          country_code: "IT",
        },
      },
    }),
  }
);

const location = await response.json();
const locationId = location.id;

Beispielantwort (201 Created)

{
  "content": {
    "address": {
      "city": "Roma",
      "code": "00100",
      "country": "IT",
      "line": {
        "number": "1",
        "street": "Via Roma",
        "type": "STREET_NUMBER"
      }
    },
    "created_at": "2026-03-05T15:07:09.776328Z",
    "id": "019cbe89-d450-7501-9928-1e7d94339208",
    "mode": "INACTIVE",
    "name": "Roma Centro Branch",
    "state": "ACQUIRED",
    "systems": [
      {
        "description": "Fiscal device (SIGN IT lite).",
        "type": "FISCAL_DEVICE"
      }
    ],
    "taxpayer": {
      "id": "019cbe81-8721-7e27-99d9-1bb4a267ba56"
    },
    "type": "BRANCH",
    "updated_at": "2026-03-05T15:07:09.776328Z"
  },
  "metadata": {
    "store_code": "STORE001"
  }
}

Sobald ein Standort erstellt wurde, wird sein state standardmäßig auf ACQUIRED gesetzt. Aktualisieren Sie den Status auf COMMISSIONED über den Endpunkt updateLocation, bevor Sie fortfahren.

📘Note

Wenn der Steuerpflichtige von einem einzigen Geschäftsstandort aus tätig ist, der mit der rechtlichen Adresse übereinstimmt, ist die Erstellung eines Location::BRANCH nicht zwingend erforderlich. Ein Location::HEAD_OFFICE wird automatisch bei der Erstellung des Steuerpflichtigen angelegt und teilt dieselbe UUID wie der Steuerpflichtige. Wenn der Steuerpflichtige auf COMMISSIONED gesetzt wird, wird der Location::HEAD_OFFICE automatisch ebenfalls auf COMMISSIONED gesetzt.

System (FISCAL_DEVICE) erstellen

Der Endpunkt createSystem ermöglicht die Erstellung einer Abstraktion jedes elektronischen Aufzeichnungssystems (ERS), das für steuerliche Vorgänge verwendet wird. Jede Registrierkasse oder jeder Point of Sale muss als neues System vom Typ FISCAL_DEVICE bereitgestellt werden.

Ein System wird mit einem bestimmten, zuvor erstellten Standort verbunden.
Für jedes System müssen Sie Informationen zu producer und software angeben, um nachzuverfolgen, welches Gerät steuerliche Transaktionen durchführt. Weitere Informationen finden Sie in diesem FAQ-Artikel.

curl -X POST https://test.api.fiskaly.com/systems \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "type": "FISCAL_DEVICE",
      "location": {
        "id": "your_location_id"
      },
      "producer": {
        "type": "MPN",
        "number": "FD-001",
        "details": {
          "name": "My Fiscal Device"
        }
      },
      "software": {
        "name": "My POS Software",
        "version": "1.0.0"
      }
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/systems",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "FISCAL_DEVICE",
        location: {
          id: locationId,
        },
        producer: {
          type: "MPN",
          number: "FD-001",
          details: {
            name: "My Fiscal Device",
          },
        },
        software: {
          name: "My POS Software",
          version: "1.0.0",
        },
      },
    }),
  }
);

const system = await response.json();
const systemId = system.id;

Beispielantwort (201 Created)

{
  "content": {
    "compliance": {
      "software": {
        "name": "My POS Software",
        "version": "1.0.0"
      }
    },
    "created_at": "2026-03-05T13:57:00.016909Z",
    "id": "019cbe49-97f0-7dde-adae-e10fea9d64c9",
    "journal": {
      "cryptography": {
        "certificate": {
          "expires_at": "2029-03-05T13:57:00Z",
          "serial_number": "7E7D991D5D1768AF224A754A3E815537",
          "x509_pem": "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIQfn2ZHV0XaK8iSnVKPoFVNzANBgkqhkiG9w0BAQsFADAT\nMREwDwYDVQQKEwhmaXNrYWx5LjAeFw0yNjAzMDUxMzU3MDBaFw0yOTAzMDUxMzU3\nMDBaMBMxETAPBgNVBAoTCGZpc2thbHkuMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\nMIIBCgKCAQEAzE++CjP6UrE9d4ftaRU50yWWycU1/ql5iLgpFjjBZdXAuay82ely\n11sMfjlL3RJaIkIF8w9VcrnaCnSJLzSihEPcohFF8B9iX+/GLHA9FNHMpRrNBaC/\nMmXv7iuPkOFZDTxueWtkti0BqEE+H3RoCsOkPxzMMQ0UYCtZx9V5i/bXO+Akb8HC\nuq80+73m/DP1WFQgD6d/vwfqr+eM4jZTUiRPyy9W6yBOj02SbFL6Oeop2yDNo7Ws\nhZLoquNgVe9lEHZV2N62AVe1OEXdDzn2BlNvCnlwb9RJCGTVCMQbOsN84EMhpwOG\nsRNHgezSeGhO7aca+/igmiuSW7Uw3YdWWwIDAQABo0IwQDAOBgNVHQ8BAf8EBAMC\nAoQwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUn+BqmtpyTeC4wdZNEMYf96hV\ny78wDQYJKoZIhvcNAQELBQADggEBACXaL/EXGW4PnjC+Dj5ZUySE5vtysPUV0Tkw\n4+EtLJUs86itNZgyhQpXfwzvpgj/wL7XA+GAnPqpUbrMOXLawsWGtID8BZHrQRRJ\ny/ZcHRQyIwoHNNl5bbDDNC/icG78GhK+RmdCw3wcVyxABBzpE/CckNn4hltsCqUo\n01eqms+SmY+MBUBj3ec1iVcD0bz/pyMmIQSVfWjKWtHofwUTCkgEm9cKqtyfajzB\ne6bKoScTziojhlCtnEfPb20vtQ+UE183FOG36WfuRV8EtS+3Cgx83yEj8QXVuYcA\nKQAgoPy6/6xHMDkZH3P/XTOfBf8UkZvQy5egibgC6k2wqjxYWtY=\n-----END CERTIFICATE-----\n"
        },
        "signature": {
          "hash": "SHA-256",
          "type": "RSA"
        }
      }
    },
    "kind": "INTERNAL",
    "location": {
      "id": "019cbe89-d450-7501-9928-1e7d94339208"
    },
    "mode": "INACTIVE",
    "producer": {
      "details": {
        "name": "My Fiscal Device"
      },
      "number": "FD-001",
      "type": "MPN"
    },
    "records": [
      {
        "description": "Intention of an upcoming transaction.",
        "type": "INTENTION::TRANSACTION"
      },
      {
        "description": "Receipt transaction information.",
        "type": "TRANSACTION::RECEIPT"
      },
      {
        "description": "Correction of an issued transaction.",
        "type": "TRANSACTION::CORRECTION"
      },
      {
        "description": "Cancellation of an issued transaction.",
        "type": "TRANSACTION::CANCELLATION"
      }
    ],
    "software": {
      "name": "SIGN IT Lite",
      "version": "v1.0.0"
    },
    "state": "ACQUIRED",
    "type": "FISCAL_DEVICE",
    "updated_at": "2026-03-05T13:57:00.016909Z",
    "vat_exemptions": [
      {
        "code": "NOT_SUBJECT",
        "description": "Not subject (Non soggette)"
      },
      {
        "code": "NOT_TAXABLE",
        "description": "Not taxable (Non imponibili)"
      },
      {
        "code": "CAUSE_1",
        "description": "Exempt (Esenti)"
      },
      {
        "code": "CAUSE_2",
        "description": "Exclusive Art. 15"
      },
      {
        "code": "CAUSE_3",
        "description": "Marginal scheme (Regime del margine)"
      },
      {
        "code": "CAUSE_4",
        "description": "Other (Altre non IVA)"
      }
    ],
    "vat_rates": [
      {
        "code": "STANDARD",
        "description": "Standard VAT rate",
        "historic": false,
        "percentage": "22"
      },
      {
        "code": "REDUCED_1",
        "description": "Reduced VAT rate 1",
        "historic": false,
        "percentage": "10"
      },
      {
        "code": "REDUCED_2",
        "description": "Reduced VAT rate 2",
        "historic": false,
        "percentage": "5"
      },
      {
        "code": "REDUCED_3",
        "description": "Super-reduced VAT rate",
        "historic": false,
        "percentage": "4"
      }
    ]
  }
}

Sobald ein System erstellt wurde, wird sein state standardmäßig auf ACQUIRED gesetzt. Um Datensätze zu erstellen, muss sein Status auf COMMISSIONED über den Endpunkt updateSystem aktualisiert werden.

Datensatz erstellen

Für jeden im System durchgeführten Geschäftsvorgang muss der Endpunkt createRecord in zwei aufeinanderfolgenden Aufrufen verwendet werden:

Teil A) INTENTION: erfasst die Absicht, eine TRANSACTION zu starten
Teil B) TRANSACTION: stellt die Transaktionsdaten bereit

Teil A) Intention erstellen

Ein Datensatz vom Typ INTENTION enthält die Verknüpfung mit dem System, das die Transaktion durchführen wird, und eine Operation vom Typ TRANSACTION, die die Absicht des Systems zur Erfassung einer Transaktion repräsentiert.

curl -X POST https://test.api.fiskaly.com/records \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "type": "INTENTION",
      "system": {
        "id": "your_system_id"
      },
      "operation": {
        "type": "TRANSACTION"
      }
    }
  }'

const intentionResponse = await fetch(
  "https://test.api.fiskaly.com/records",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "INTENTION",
        system: {
          id: systemId,
        },
        operation: {
          type: "TRANSACTION",
        },
      },
    }),
  }
);

const intention = await intentionResponse.json();
const intentionId = intention.id;

Beispielantwort (201 Created)

{
  "content": {
    "file": {
      "location": "SERVICE"
    },
    "id": "019cbe96-8e57-7693-a4ef-4ed89a76ef9b",
    "journal": {
      "signature": "yrrXNoHGF0YYPVgUWH81tXQYCf6H3BCjTed6YUT2ZvmmRaq8qoZAUOaP8wJI4ipN",
      "signed_at": "2026-03-05T15:21:03.84326335Z"
    },
    "mode": "PROCESSING",
    "operation": "{\"type\":\"TRANSACTION\"}",
    "state": "ACCEPTED",
    "system": {
      "id": "019cbe96-7245-7b49-91d6-ba66a235fc72"
    },
    "type": "INTENTION::TRANSACTION"
  }
}

Teil B) Transaktion erstellen

Ein Datensatz vom Typ TRANSACTION ist mit der zuvor erstellten INTENTION verknüpft und kann eine der folgenden Operationen durchführen:

RECEIPT: Repräsentiert den Verkauf einer Ware oder Dienstleistung, einschließlich Dokumentdetails (z. B. Belegnummer, Gesamtbeträge inklusive und exklusive Mehrwertsteuer) und Einzelpositionen (Kennzeichnung eines SALE, Beschreibung, ob es sich um eine GOOD oder SERVICE handelt usw.).
CORRECTION: Repräsentiert einen Rückgabeprozess. Enthält dieselben Daten wie eine RECEIPT-Operation, plus eine Referenz-id auf das ursprüngliche RECEIPT-Dokument.
CANCELLATION: Wird verwendet, um eine gesamte Transaktion zu stornieren. Erfordert die id eines zuvor erstellten Datensatzes.

curl -X POST https://test.api.fiskaly.com/records \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "type": "TRANSACTION",
      "record": {
        "id": "your_intention_id"
      },
      "operation": {
        "type": "RECEIPT",
        "document": {
          "number": "1",
          "total_vat": {
            "amount": "2.20",
            "exclusive": "10.00",
            "inclusive": "12.20"
          }
        },
        "entries": [
          {
            "type": "SALE",
            "details": {
              "concept": "GOOD"
            },
            "data": {
              "type": "ITEM",
              "text": "Margherita Pizza",
              "unit": {
                "quantity": "1",
                "price": "12.20"
              },
              "value": {
                "base": "10.00",
                "discount": "0.00"
              },
              "vat": {
                "type": "VAT_RATE",
                "code": "STANDARD",
                "percentage": "22.00",
                "exclusive": "10.00",
                "inclusive": "12.20",
                "amount": "2.20"
              }
            }
          }
        ],
        "payments": [
          {
            "type": "CASH",
            "details": {
              "amount": "12.20"
            }
          }
        ]
      }
    }
  }'

const transactionResponse = await fetch(
  "https://test.api.fiskaly.com/records",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "TRANSACTION",
        intention: {
          id: intentionId,
        },
        operation: {
          type: "RECEIPT",
          document: {
            number: 1,
            date: "2026-02-03",
            total: {
              amount_incl_vat: "12.20",
              amount_excl_vat: "10.00",
            },
          },
          entries: [
            {
              type: "SALE",
              description: "Margherita Pizza",
              category: "GOOD",
              quantity: 1,
              unit_price: "10.00",
              vat_rate: "22.00",
              amount_incl_vat: "12.20",
            },
          ],
        },
      },
    }),
  }
);

const transaction = await transactionResponse.json();

Beispielantwort (201 Created)

{
  "content": {
    "compliance": {
      "data": "DCW0000/0000-0000",
      "url": "https://ivaservizi.agenziaentrate.gov.it/ser/api/documenti/v1/doc/documenti/00000000/stampa/"
    },
    "file": {
      "location": "SERVICE"
    },
    "id": "019cbea1-4775-7b70-9b83-79cac7107266",
    "journal": {
      "record": {
        "id": "019cbe96-8e57-7693-a4ef-4ed89a76ef9b"
      },
      "signature": "vGQtUR29rogalpYCVIJPnu-3gPLScA5wEEyxrllfviUGvoK2lkLj5bw3OimfvzuP",
      "signed_at": "2026-03-05T15:32:46.594042649Z"
    },
    "mode": "FINISHED",
    "operation": "{\"document\":{\"number\":\"1\",\"total_vat\":{\"amount\":\"2.20\",\"exclusive\":\"10.00\",\"inclusive\":\"12.20\"}},\"entries\":[{\"data\":{\"text\":\"Margherita Pizza\",\"type\":\"ITEM\",\"unit\":{\"price\":\"12.20\",\"quantity\":\"1\"},\"value\":{\"base\":\"10.00\",\"discount\":\"0.00\"},\"vat\":{\"amount\":\"2.20\",\"code\":\"STANDARD\",\"exclusive\":\"10.00\",\"inclusive\":\"12.20\",\"percentage\":\"22.00\",\"type\":\"VAT_RATE\"}},\"details\":{\"concept\":\"GOOD\",\"purpose\":\"STANDARD\"},\"type\":\"SALE\"}],\"payments\":[{\"details\":{\"amount\":\"12.20\"},\"type\":\"CASH\"}],\"type\":\"RECEIPT\"}",
    "record": {
      "id": "019cbe96-8e57-7693-a4ef-4ed89a76ef9b"
    },
    "state": "COMPLETED",
    "system": {
      "id": "019cbe49-97f0-7dde-adae-e10fea9d64c9"
    },
    "transmission": {
      "request": {
        "data": "e30A",
        "type": "application/json"
      },
      "response": {
        "data": "e30A",
        "type": "application/json"
      }
    },
    "type": "TRANSACTION::RECEIPT"
  }
}

Sobald die Transaktion ordnungsgemäß erfasst wurde und die Handelsdokumentinformationen erfolgreich an das Webportal der AdE übermittelt wurden (Status COMPLETED, Modus FINISHED), enthält die in der API-Antwort zurückgegebene compliance.data die von der AdE dem Handelsdokument zugewiesene Progressivnummer (DCW-Nummer) und, falls angegeben, den Lotterie-Code des Verbrauchers.

Hinweis: Wenn stattdessen ein Status REJECTED oder FAILED zurückgegeben wird, lesen Sie bitte unseren Abschnitt Datensatz-Status und -Modi für weitere Hinweise.

📘Note

Alle in der LIVE-Umgebung erstellten Datensätze werden an die Steuerbehörden übermittelt und erzeugen gültige Handelsdokumente. Daher müssen diese Dokumente immer tatsächliche Transaktionen widerspiegeln.

Nächste Schritte

SIGN IT API-Referenz

Vollständige API-Dokumentation für den SIGN IT-Endpunkt — alle Ressourcen, Parameter und Antworten.

Handhabung von Verbindungsunterbrechungen

Erfahren Sie, wie Sie Verbindungsunterbrechungsszenarien handhaben und die Steuerkonformität bei Ausfällen gewährleisten.

Glossar

Schlüsselbegriffe und Definitionen für das italienische Steuerkonformiätssystem.

HUB-Leitfaden

Erfahren Sie, wie Sie Organisationen, API Key und Ressourcen über den fiskaly HUB verwalten.

Was this page helpful?

Schrittweise Integration

Integrationsablauf

Voraussetzungen

Schrittweise Einrichtung

Im HUB registrieren

Account & Organisation GROUP erstellen

API Key erstellen

Token erstellen

Organisation UNIT erstellen

Subject (API Key) erstellen

Token erstellen

Steuerpflichtigen erstellen

Standort erstellen

System (FISCAL_DEVICE) erstellen

Datensatz erstellen

Nächste Schritte

SIGN IT API-Referenz

Handhabung von Verbindungsunterbrechungen

Glossar

HUB-Leitfaden