Schritt-für-Schritt-Integration

⚠️ Sie sehen die Dokumentation für API-Version 2024-10-31. Die neueste Version ist 2026-05-04. Wesentliche Änderungen umfassen aktualisierte Terminologie (Asset → Organization, Entity → Taxpayer/Location).

Um mit dem Integrationsprozess zu beginnen, lesen Sie bitte die hier bereitgestellten detaillierten Schritt-für-Schritt-Anweisungen.

Das begleitende Diagramm veranschaulicht den Workflow und hebt die wesentlichen Schritte hervor, die erforderlich sind, um Ihre Integration erfolgreich abzuschließen. Hierfür müssen Sie unsere SIGN IT verwenden.

Schritt 1: Auf dem Dashboard registrieren

Beginnen Sie mit der Registrierung auf dem Dashboard.

Die Erstellung eines fiskaly-Kontos 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.

📘video tutorial

Sehen Sie sich unser Video für eine Schritt-für-Schritt-Erklärung an, wie Sie Ihr Konto und Ihre erste Organisation einrichten.

Schritt 2: Erste Organisation erstellen

Fahren Sie mit der Erstellung Ihrer ersten Organisation über das Dashboard fort. Diese Organisation repräsentiert den POS-Anbieter oder Einzelhändler mit seinem eigenen POS-System.

Schritt 3: API Key erstellen

Der nächste Schritt ist die Generierung eines API Keys für Ihre Organisation über das Dashboard. Dieses API Key-und-Geheimnis-Paar ist erforderlich, um Ihr erstes Asset vom Typ UNIT zu erstellen (Schritt 5).

Beachten Sie, dass in der TEST-Umgebung generierte API Key TEST-Ressourcen erstellen, während API Key aus der LIVE-Umgebung LIVE-Ressourcen erstellen. Weitere Informationen finden Sie in unserem Artikel zu TEST- und LIVE-Umgebungen.

Ab dem nächsten Schritt werden Sie unsere SIGN IT API verwenden. Sie können unsere Postman-Sammlung für SIGN IT herunterladen, die Ihre Integration in den nächsten Schritten erleichtern könnte.

Schritt 4: MANAGEMENT - Token erstellen

Beginnen Sie mit der Verwendung der SIGN IT API über den createToken-Endpunkt. Sie müssen einen Token zur Authentifizierung für die nächsten Schritte erstellen.

Schritt 5: MANAGEMENT - Asset UNIT erstellen

Fahren Sie mit der Erstellung eines Assets vom Typ UNIT über den createAsset-Endpunkt fort. Sie müssen ein Asset UNIT für jede Ihrer Steuerpflichtigenrepräsentationen erstellen.

Bei der Erstellung Ihres ersten Assets vom Typ UNIT stellen Sie sicher, dass es mit der UUID der ersten Organisation, die Sie über das Dashboard erstellt haben, verknüpft ist. Verwenden Sie dazu den Token, der aus den in der ersten Organisation erstellten API Keys generiert wurde. Dies spiegelt die hierarchische Struktur wider, bei der die UNIT unter der ersten Organisation verschachtelt ist.

Schritt 6: MANAGEMENT - Subject (API Key) erstellen

Erstellen Sie ein Subject vom Typ API_KEY über den createSubject-Endpunkt. Die Verbindung zwischen dem Asset UNIT und dem API Key wird über den X-Scope-Identifier hergestellt (unter Verwendung der id des neu erstellten Assets).

Schritt 7: MANAGEMENT - Neuen Token erstellen

Erstellen Sie als Nächstes einen Token, der zum Erstellen von Ressourcen innerhalb des entsprechenden Asset UNIT verwendet wird.

Schritt 8: OPERATION - Entity COMPANY oder INDIVIDUAL erstellen

Jetzt können Sie mit der Erstellung der operativen Teile beginnen, die für die Fiskalisierung in Italien erforderlich sind. Verwenden Sie dazu den createEntity-Endpunkt, um die Repräsentation eines Steuerpflichtigen wie folgt zu erstellen:

• Sie müssen den Steuerpflichtigen als Entity vom Typ Company (juristische Person) oder Individual (natürliche Person) einrichten. In beiden Fällen müssen name und address angegeben werden.
• Innerhalb der italienischen fiscalization-Informationen müssen die folgenden Steuerpflichtigen-Daten angegeben werden:
  • tax_id_number: Italienischer Steuercode (Codice fiscale),
  • vat_id_number: Italienische Umsatzsteuer-Identifikationsnummer (Partita IVA),
  • credentials: Pin und Passwort, die für den Zugang zu den Diensten der AdE erforderlich sind. Weitere Informationen finden Sie in unserem Abschnitt Anmeldeinformationen.

Sobald Sie eine Entity vom Typ Company oder Individual erstellen, wird ihr state auf ACQUIRED gesetzt. Um voll funktionsfähig zu sein, muss der Zustand über den updateEntity-Endpunkt auf COMMISSIONED aktualisiert werden.

📘Note

Nur Fisconline-Anmeldeinformationen sind für die Nutzung von SIGN IT lite gültig. Ihre Anmeldeinformationen müssen alle 60 Tage aktualisiert werden.

📘important

Der Steuerpflichtige muss sich manuell erstmals beim Webportal der Steuerbehörde anmelden, um sicherzustellen, dass die Anmeldeinformationen ordnungsgemäß funktionieren und die Nutzungsbedingungen sowie zusätzliche Klauseln zu akzeptieren.

Schritt 9: OPERATION - Entity LOCATION erstellen

Für jeden operativen Geschäftsstandort müssen Sie eine Entity vom Typ Location über den createEntity-Endpunkt erstellen.

Wenn Sie eine Entity vom Typ Location erstellen, wird ihr state zunächst auf ACQUIRED gesetzt. Um fortzufahren, müssen Sie den Zustand über den updateEntity-Endpunkt auf COMMISSIONED ändern.

Schritt 10: OPERATION - System erstellen

Der createSystem-Endpunkt ermöglicht es Ihnen, eine Abstraktion jedes Geräts zu erstellen, das Sie zur Ausstellung von Belegen verwenden. Das bedeutet, dass jede Kasse oder jeder Verkaufspunkt als neues System in der SIGN IT API bereitgestellt werden muss. Dafür muss der System-Typ FISCAL_DEVICE ausgewählt werden.

• Ein System wird mit einer bereits erstellten Entity verbunden (ob vom Typ Company oder Individual, oder einem bestimmten Standort, falls dieser sich von der rechtlichen Adresse unterscheidet).
• Für jedes Gerät müssen Sie Produktinformationen wie MPN, Marke und Datum des Nutzungsbeginns sowie den Softwarenamen und die Version auf dem Gerät angeben. Diese Informationen gewährleisten eine ordnungsgemäße Verfolgung, welches Gerät Steuertransaktionen durchführt.

Wenn Sie ein System erstellen, wird sein Anfangszustand auf ACQUIRED gesetzt. Um Records erstellen zu können, muss sein state über den updateSystem-Endpunkt auf COMMISSIONED aktualisiert werden.

Schritt 11: OPERATION - Record erstellen

💡Tip

Das Erstellen eines Records in der SIGN IT API erfordert immer zwei aufeinanderfolgende Aufrufe: Teil A) INTENTION (genau zu Beginn des Verkaufsprozesses) und Teil B) TRANSACTION (direkt nach dem Zahlungsprozess).

TEIL A) Intention

Für jeden in der Kasse oder am POS durchgeführten Geschäftsvorgang wird der createRecord-Endpunkt der SIGN IT API in zwei Aufrufen verwendet: der erste zur Erfassung der Absicht, eine Transaktion zu beginnen, und der zweite zur Bereitstellung der Transaktionsdaten.

Ein Record vom Typ Intention enthält folgende Informationen:

• Zuordnung zu einem System, das die Transaktion durchführt.
• Vorgang vom Typ Transaction: Das bedeutet, der Vorgang, den das System auszuführen beabsichtigt, ist die Aufzeichnung einer Transaktion.

Teil B) Transaction

Der letzte Schritt zur Ausstellung eines konformen Belegs in Italien besteht darin, einen weiteren Aufruf an den createRecord-Endpunkt zu machen, der einen Record vom Typ Transaction angibt.

Jedes Transaction-Dokument wird mit dem internen Bezeichner eines bereits erstellten Records vom Typ Intention verknüpft und kann Details für Schulungszwecke enthalten (Dokumente, die im Trainings- oder Testmodus ausgestellt werden).

Die Transaction kann zur Durchführung einer der folgenden Vorgänge in Italien verwendet werden:

• RECEIPT: Dieser Vorgang enthält alle erforderlichen Informationen zur Erstellung eines Verkaufs-Handelsdokuments in Italien:
  • Dokumentinformationen wie Nummer, Aktivitätscode (falls zutreffend), Transaktionsdatum und Gesamtbeträge des Dokuments (einschließlich und ausschließlich Mehrwertsteuer)
  • Informationen zu jedem Eintrag oder Einzelposten des Vorgangs:
    • Identifizierung eines Verkaufs
    • Beschreibung
    • Angabe, ob es sich um eine Ware oder eine Dienstleistung handelt
• CORRECTION: Dieser Vorgangstyp wird zur Darstellung eines Rückgabevorgangs verwendet. Er enthält die gleichen Daten wie ein Vorgang vom Typ RECEIPT und zusätzlich:
  • Referenz-id auf einen bereits erstellten Beleg (ursprüngliches Transaktionsdokument)
• CANCELLATION: Dieser Vorgang wird zur Ungültigmachung einer gesamten Transaktion verwendet. Hierfür muss die id eines zuvor erstellten Records angegeben werden.

In allen Fällen zeigt die konforme Antwort auf die Datensatzerstellung nach ordnungsgemäßer Erfassung der Transaktion und erfolgreicher Übermittlung der Handelsdokumentinformationen an das Webportal der AdE die von der AdE dem Handelsdokument zugewiesene Progressive Number und den Lotterie-Code des Verbrauchers an (falls im übermittelten Payload angegeben).

📘Note

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