Schritt-für-Schritt-Integrierung
Dieser Leitfaden führt Sie durch den gesamten Prozess der Integrierung der fiskaly SIGN FR API für die französische Fiskalkonformität, unter Verwendung einer Kombination aus dem fiskaly HUB und API-Anfragen. Am Ende werden Sie ein vollständig funktionierendes System haben, bei dem Datensätze signiert, journalisiert und archiviert werden.
Bevor Sie mit der Einrichtung beginnen, folgt hier eine Übersicht dessen, was Sie konfigurieren werden:
Organization
- AccountVon HUB generiert
Übergeordnete Einheit in fiskaly HUB. Kann nicht innerhalb eines anderen Accounts verschachtelt werden.
- GroupVon HUB generiert
Zwischenschicht zur Organisation von Units in logische Cluster (z.B. eine pro Land).
- UnitVon API generiert
Merchant / Taxpayer, der innerhalb der Group tätig ist.
API Key & Secret
- Group-EbeneVon HUB generiert
Im HUB für die Organization
GROUPgeneriert. Wird zur Authentifizierung in der SIGN FR API verwendet, um Organization Units und deren API Keys zu erstellen. - Unit-EbeneVon API generiert
Über die API (Endpoint
createSubject) für die Organization UNIT generiert. Wird für alle operativen Aufrufe auf Unit-Ebene verwendet.
Taxpayer
Repräsentation einer COMPANY oder eines INDIVIDUAL, die bei den französischen Steuerbehörden registriert ist.
Location
- HEAD_OFFICE
Automatisch bei Erstellung des Taxpayers angelegt, teilt dieselbe UUID. Entspricht der Geschäftsadresse.
- BRANCH
Jedes Geschäft, jede Filiale oder sonstige Betriebsstätte, in der fiskalische Vorgänge stattfinden.
System
- FISCAL_DEVICE
Abstraktion einer Registrierkasse zur Erfassung von Transaktionsdaten gemäß den französischen Fiskalvorschriften (NF525).
Record
Jeder Geschäftsvorfall, der im System durchgeführt wird. Erfordert zwei aufeinanderfolgende API-Aufrufe:
- INTENTION
Gibt die Absicht an, eine Transaktion im System zu erfassen.
- TRANSACTION
Gibt einen vom System ausgestellten Fiskalbeleg an.
Voraussetzungen
Abschnitt betitelt „Voraussetzungen“Sie benötigen ein fiskaly-Konto und Zugang zum fiskaly HUB. Wenn Sie noch kein Konto haben, registrieren Sie sich hier.
Sie benötigen außerdem ein Tool zur Durchführung von HTTP-Anfragen — zum Beispiel cURL (Kommandozeile), Postman oder Ihren eigenen Anwendungscode.
API-Schlüssel, die in der TEST-Umgebung generiert wurden, erstellen TEST-Ressourcen, während solche aus der LIVE-Umgebung LIVE-Ressourcen erstellen. Weitere Einzelheiten finden Sie in unserem Artikel über TEST- und LIVE-Umgebungen.
Integrierungs-Workflow
Abschnitt betitelt „Integrierungs-Workflow“Das folgende Diagramm veranschaulicht den Arbeitsablauf und hebt die wesentlichen Schritte hervor, die für eine erfolgreiche Integrierung erforderlich sind. Jede Kachel verlinkt direkt auf den entsprechenden Einrichtungsschritt unten.
Gelb markierte Schritte müssen direkt im HUB durchgeführt werden, während die übrigen Schritte über die API abgewickelt werden müssen. Die korrekte Durchführung jeder Aktion im richtigen Kontext ist ein wichtiger Schritt für eine erfolgreiche Integrierung.
Schritt-für-Schritt-Einrichtung
Abschnitt betitelt „Schritt-für-Schritt-Einrichtung“Im HUB registrieren
Beginnen Sie mit der Registrierung im fiskaly HUB.

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-Schlüssels fortfahren.
📘Video-TutorialSehen Sie sich unser Video für eine Schritt-für-Schritt-Erklärung zur Einrichtung Ihres Kontos und Ihrer ersten Organisation an.
Account & Group erstellen
Fahren Sie fort mit der Erstellung Ihres Accounts und Ihrer ersten Group über den HUB. In der SIGN FR API ist die GROUP eine erforderliche Zwischenschicht innerhalb Ihres ACCOUNT, die zur Organisation Ihrer UNIT-Organisationen verwendet wird.
API-Schlüssel erstellen
Der nächste Schritt ist die Generierung eines API-Schlüssels für Ihre Organisation über den HUB. Dieses API-Schlüssel- und Secret-Paar ist erforderlich, um Ihre Organisation(en) vom Typ
UNITzu erstellen (Schritt 5).⚠️Anmeldedaten sicher aufbewahrenDas API-Secret wird nur einmal angezeigt. Stellen Sie sicher, dass Sie es kopieren und an einem sicheren Ort speichern, bevor Sie den Dialog schließen.
Ab dem nächsten Schritt werden Sie unsere SIGN FR API verwenden.
Token erstellen (Verwaltung)
Beginnen Sie die Nutzung der SIGN FR API über den createToken-Endpunkt. Sie müssen ein Token erstellen, um sich für die nächsten Schritte zu authentifizieren.
curl -X POST https://test.api.fiskaly.com/api/v1/auth/token \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -d '{ "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET" }'const response = await fetch( "https://test.api.fiskaly.com/api/v1/auth/token", { method: "POST", headers: { "Content-Type": "application/json", "X-Api-Version": "2026-02-03", }, body: JSON.stringify({ api_key: "YOUR_API_KEY", api_secret: "YOUR_API_SECRET", }), } ); const { access_token } = await response.json();Beispielantwort (200 OK)
{"content": {"id": "tok_abc123","authentication": {"type": "JWT","bearer": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...","expires_at": "2026-03-02T12:00:00Z"},"organization": {"id": "YOUR_GROUP_ORG_ID"},"subject": {"id": "sub_abc123"}},"metadata": {"trace_identifier": "trace_abc123","api_version": "2026-02-03"}}Organisation UNIT erstellen
Fahren Sie fort mit der Erstellung einer Organisation vom Typ
UNITüber den createOrganization-Endpunkt. Sie müssen eine OrganisationUNITfür jede Ihrer Steuerpflichtigen-Repräsentationen erstellen.Beim Erstellen einer Organisation vom Typ
UNITstellen Sie sicher, dass sie mit der Organisation vom TypGROUPverknüpft ist, die Sie zuvor über den HUB erstellt haben. Verwenden Sie dazu das Token, das aus den API-Schlüsseln Ihrer Organisation vom TypGROUPgeneriert wurde. Dies spiegelt die hierarchische Struktur wider, bei der die Organisation vom TypUNITder Organisation vom TypGROUPuntergeordnet ist.curl -X POST https://test.api.fiskaly.com/api/v1/organizations \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \ -H "X-Scope-Identifier: YOUR_GROUP_ORG_ID" \ -d '{ "type": "UNIT", "name": "My UNIT Organization", "parent_id": "YOUR_GROUP_ORG_ID" }'const response = await fetch( "https://test.api.fiskaly.com/api/v1/organizations", { method: "POST", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Idempotency-Key": crypto.randomUUID(), "X-Scope-Identifier": "YOUR_GROUP_ORG_ID", }, body: JSON.stringify({ type: "UNIT", name: "My UNIT Organization", parent_id: "YOUR_GROUP_ORG_ID", }), } ); const organization = await response.json();Beispielantwort (201 Created)
{"content": {"id": "org_unit_abc123","state": "ENABLED","type": "UNIT","name": "My UNIT Organization","organization": {"id": "YOUR_GROUP_ORG_ID"}},"metadata": {"trace_identifier": "trace_abc123","api_version": "2026-02-03"}}Subject API-Schlüssel erstellen
Erstellen Sie ein Subject vom Typ
API_KEYüber den createSubject-Endpunkt. Die Verbindung zwischen der Organisation vom TypUNITund dem API-Schlüssel wird über denX-Scope-Identifierhergestellt (unter Verwendung deridder neu erstellten Organisation).curl -X POST https://test.api.fiskaly.com/api/v1/subjects \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "type": "API_KEY" }'const response = await fetch( "https://test.api.fiskaly.com/api/v1/subjects", { method: "POST", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Idempotency-Key": crypto.randomUUID(), "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ type: "API_KEY", }), } ); const subject = await response.json(); const { api_key, api_secret } = subject.content.credentials;Beispielantwort (201 Created)
{"content": {"id": "sub_abc123","state": "ENABLED","type": "API_KEY","credentials": {"api_key": "fsk_unit_abc123","api_secret": "secret_only_shown_once"}},"metadata": {"trace_identifier": "trace_abc123","api_version": "2026-02-03"}}Token erstellen (UNIT)
Erstellen Sie als Nächstes ein Token, das zur Erstellung von Ressourcen innerhalb der entsprechenden Organisation vom Typ
UNITverwendet wird.curl -X POST https://test.api.fiskaly.com/api/v1/auth/token \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -d '{ "api_key": "YOUR_UNIT_API_KEY", "api_secret": "YOUR_UNIT_API_SECRET" }'const response = await fetch( "https://test.api.fiskaly.com/api/v1/auth/token", { method: "POST", headers: { "Content-Type": "application/json", "X-Api-Version": "2026-02-03", }, body: JSON.stringify({ api_key: "YOUR_UNIT_API_KEY", api_secret: "YOUR_UNIT_API_SECRET", }), } ); const { access_token } = await response.json();Beispielantwort (200 OK)
{"content": {"id": "tok_unit_abc123","authentication": {"type": "JWT","bearer": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...","expires_at": "2026-03-02T12:00:00Z"},"organization": {"id": "org_unit_abc123"},"subject": {"id": "sub_abc123"}},"metadata": {"trace_identifier": "trace_abc123","api_version": "2026-02-03"}}Steuerpflichtigen erstellen
Jetzt sind Sie bereit, die operativen Teile für die Fiskalisierung in Frankreich zu erstellen. Verwenden Sie den createTaxpayer-Endpunkt, um die Repräsentation eines Steuerpflichtigen zu erstellen:
- Legen Sie den Steuerpflichtigen als Typ
COMPANY(juristische Person) oderINDIVIDUAL(natürliche Person) fest. In beiden Fällen müssennameundaddressangegeben werden. - Geben Sie innerhalb der französischen
fiscalization-Informationen Folgendes an:tax_id_number: Französische Unternehmensidentifikationsnummer (SIREN), ausgestellt von INSEEcredentials: Anmeldedaten für das französische Fiskalisierungsportal
Nach der Erstellung wird der
statedes Steuerpflichtigen aufACQUIREDgesetzt. Aktualisieren Sie ihn mit dem updateTaxpayer-Endpunkt aufCOMMISSIONED.# Steuerpflichtigen erstellen curl -X POST https://test.api.fiskaly.com/api/v1/taxpayers \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "type": "COMPANY", "name": "My Company", "address": { "street": "123 Rue de Rivoli", "postal_code": "75001", "city": "Paris", "country_code": "FR" }, "fiscalization": { "tax_id_number": "123456789", "credentials": { "type": "PORTAL_ACCESS", "username": "YOUR_PORTAL_USERNAME", "password": "YOUR_PORTAL_PASSWORD" } } }' # Steuerpflichtigen in Betrieb nehmen curl -X PATCH https://test.api.fiskaly.com/api/v1/taxpayers/YOUR_TAXPAYER_ID \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "state": "COMMISSIONED" }'// Steuerpflichtigen erstellen const createResponse = await fetch( "https://test.api.fiskaly.com/api/v1/taxpayers", { method: "POST", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Idempotency-Key": crypto.randomUUID(), "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ type: "COMPANY", name: "My Company", address: { street: "123 Rue de Rivoli", postal_code: "75001", city: "Paris", country_code: "FR", }, fiscalization: { tax_id_number: "123456789", credentials: { type: "PORTAL_ACCESS", username: "YOUR_PORTAL_USERNAME", password: "YOUR_PORTAL_PASSWORD", }, }, }), } ); const taxpayer = await createResponse.json(); // Steuerpflichtigen in Betrieb nehmen await fetch( `https://test.api.fiskaly.com/api/v1/taxpayers/${taxpayer.content.id}`, { method: "PATCH", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ state: "COMMISSIONED", }), } );- Legen Sie den Steuerpflichtigen als Typ
Standort erstellen
Erstellen Sie für jeden operativen Geschäftsstandort einen
Locationvom TypBRANCHüber den createLocation-Endpunkt.Nach der Erstellung wird der
statedes Standorts aufACQUIREDgesetzt. Aktualisieren Sie ihn mit dem updateLocation-Endpunkt aufCOMMISSIONED.# Standort erstellen curl -X POST https://test.api.fiskaly.com/api/v1/locations \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "type": "BRANCH", "address": { "street": "123 Rue de Rivoli", "postal_code": "75001", "city": "Paris", "country_code": "FR" } }' # Standort in Betrieb nehmen curl -X PATCH https://test.api.fiskaly.com/api/v1/locations/YOUR_LOCATION_ID \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "state": "COMMISSIONED" }'// Standort erstellen const createResponse = await fetch( "https://test.api.fiskaly.com/api/v1/locations", { method: "POST", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Idempotency-Key": crypto.randomUUID(), "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ type: "BRANCH", address: { street: "123 Rue de Rivoli", postal_code: "75001", city: "Paris", country_code: "FR", }, }), } ); const location = await createResponse.json(); // Standort in Betrieb nehmen await fetch( `https://test.api.fiskaly.com/api/v1/locations/${location.content.id}`, { method: "PATCH", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ state: "COMMISSIONED", }), } );System erstellen
Der createSystem-Endpunkt ermöglicht Ihnen, eine Abstraktion jedes Geräts zu erstellen, das Sie zur Ausstellung von Quittungen verwenden. Jede Registrierkasse oder jedes Kassensystem muss als neues System vom Typ
FISCAL_DEVICEbereitgestellt werden.- Ein System wird mit einem spezifischen, zuvor erstellten
Locationvom TypBRANCHverbunden. - Geben Sie für jedes Gerät Produktinformationen (MPN, Marke, Nutzungsbeginn) und Software-Details an.
Nach der Erstellung wird der
statedes Systems aufACQUIREDgesetzt. Aktualisieren Sie ihn mit dem updateSystem-Endpunkt aufCOMMISSIONED.# System erstellen curl -X POST https://test.api.fiskaly.com/api/v1/systems \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "type": "FISCAL_DEVICE", "location_id": "YOUR_LOCATION_ID", "product": { "mpn": "POS-1000", "brand": "My POS Brand", "usage_start_date": "2026-03-01", "software": { "name": "My POS Software", "version": "1.0.0" } } }' # System in Betrieb nehmen curl -X PATCH https://test.api.fiskaly.com/api/v1/systems/YOUR_SYSTEM_ID \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "state": "COMMISSIONED" }'// System erstellen const createResponse = await fetch( "https://test.api.fiskaly.com/api/v1/systems", { method: "POST", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Idempotency-Key": crypto.randomUUID(), "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ type: "FISCAL_DEVICE", location_id: "YOUR_LOCATION_ID", product: { mpn: "POS-1000", brand: "My POS Brand", usage_start_date: "2026-03-01", software: { name: "My POS Software", version: "1.0.0", }, }, }), } ); const system = await createResponse.json(); // System in Betrieb nehmen await fetch( `https://test.api.fiskaly.com/api/v1/systems/${system.content.id}`, { method: "PATCH", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ state: "COMMISSIONED", }), } );- Ein System wird mit einem spezifischen, zuvor erstellten
Datensatz erstellen
Die Erstellung eines Datensatzes in SIGN FR erfordert zwei aufeinanderfolgende Aufrufe:
- Teil A) INTENTION — zu Beginn des Verkaufsprozesses
- Teil B) TRANSACTION — nach dem Zahlungsvorgang
# Teil A) Datensatz erstellen — INTENTION curl -X POST https://test.api.fiskaly.com/api/v1/records \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Idempotency-Key: YOUR_UNIQUE_UUID_1" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "type": "INTENTION", "system_id": "YOUR_SYSTEM_ID", "operation": { "type": "TRANSACTION" } }' # Teil B) Datensatz erstellen — TRANSACTION curl -X POST https://test.api.fiskaly.com/api/v1/records \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -H "X-Idempotency-Key: YOUR_UNIQUE_UUID_2" \ -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \ -d '{ "type": "TRANSACTION", "intention_id": "YOUR_INTENTION_RECORD_ID", "operation": { "type": "RECEIPT", "document": { "number": "R-2026-0001", "date": "2026-03-01T12:00:00Z", "amounts": { "total_including_vat": "12000", "total_excluding_vat": "10000" } }, "entries": [ { "type": "SALE", "description": "Product A", "good_or_service": "GOOD" } ] } }'// Teil A) Datensatz erstellen — INTENTION const intentionResponse = await fetch( "https://test.api.fiskaly.com/api/v1/records", { method: "POST", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Idempotency-Key": crypto.randomUUID(), "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ type: "INTENTION", system_id: "YOUR_SYSTEM_ID", operation: { type: "TRANSACTION", }, }), } ); const intention = await intentionResponse.json(); // Teil B) Datensatz erstellen — TRANSACTION const transactionResponse = await fetch( "https://test.api.fiskaly.com/api/v1/records", { method: "POST", headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json", "X-Api-Version": "2026-02-03", "X-Idempotency-Key": crypto.randomUUID(), "X-Scope-Identifier": "YOUR_UNIT_ORG_ID", }, body: JSON.stringify({ type: "TRANSACTION", intention_id: intention.content.id, operation: { type: "RECEIPT", document: { number: "R-2026-0001", date: "2026-03-01T12:00:00Z", amounts: { total_including_vat: "12000", total_excluding_vat: "10000", }, }, entries: [ { type: "SALE", description: "Product A", good_or_service: "GOOD", }, ], }, }), } ); const transaction = await transactionResponse.json();Sobald der Datensatz ordnungsgemäß erstellt wurde, werden die Daten signiert, journalisiert und archiviert, um die drei wesentlichen Fiskalpflichten in Frankreich zu erfüllen.
💡Einrichtung automatisierenDiese gesamte Abfolge von Anfragen kann in eine „Ein-Klick”- Bereitstellungslösung integriert werden, die keine manuelle Benutzerinteraktion erfordert. Die Implementierungsdetails liegen bei Ihnen.
Nächste Schritte
Abschnitt betitelt „Nächste Schritte“SIGN FR API-Referenz
Vollständige API-Dokumentation für den SIGN FR-Endpunkt — alle Ressourcen, Parameter und Antworten.
Offline-Wiedergabemodus
Erfahren Sie, wie Sie Offline-Szenarien handhaben und Transaktionen bei Wiederherstellung der Verbindung wiedergeben.
Glossar
Wesentliche Begriffe und Definitionen für das französische Fiskalkonformitätssystem.
HUB-Leitfaden
Erfahren Sie, wie Sie Organisationen, API-Schlüssel und Ressourcen über fiskaly HUB verwalten.
Was this page helpful?