Zum Inhalt springen

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 GROUP generiert. 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.

Sie benötigen außerdem ein Tool zur Durchführung von HTTP-Anfragen — zum Beispiel cURL (Kommandozeile), Postman oder Ihren eigenen Anwendungscode.

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.

SIGN FR integration workflowEleven-step SIGN FR integration workflow with tiles linking to the matching setup steps below.Register on HUBHUBCreate Account &OrganizationGROUPHUBCreate API KeyHUBCreate TokenSIGN FR APICreate OrganizationUNITSIGN FR APICreate SubjectAPI_KEYSIGN FR APICreate TokenSIGN FR APICreate TaxpayerCOMPANY orINDIVIDUALSIGN FR APICreate LocationBRANCHSIGN FR APICreate SystemFISCAL_DEVICESIGN FR APICreate RecordSIGN FR API
  1. Im HUB registrieren

    Beginnen Sie mit der Registrierung im fiskaly HUB.

    Registration

    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.

  2. 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.

  3. 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 UNIT zu erstellen (Schritt 5).

    Ab dem nächsten Schritt werden Sie unsere SIGN FR API verwenden.

  1. 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"
      }'
    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"
    }
    }
  2. Organisation UNIT erstellen

    Fahren Sie fort mit der Erstellung einer Organisation vom Typ UNIT über den createOrganization-Endpunkt. Sie müssen eine Organisation UNIT für jede Ihrer Steuerpflichtigen-Repräsentationen erstellen.

    Beim Erstellen einer Organisation vom Typ UNIT stellen Sie sicher, dass sie mit der Organisation vom Typ GROUP verknüpft ist, die Sie zuvor über den HUB erstellt haben. Verwenden Sie dazu das Token, das aus den API-Schlüsseln Ihrer Organisation vom Typ GROUP generiert wurde. Dies spiegelt die hierarchische Struktur wider, bei der die Organisation vom Typ UNIT der Organisation vom Typ GROUP untergeordnet 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"
      }'
    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"
    }
    }
  3. Subject API-Schlüssel erstellen

    Erstellen Sie ein Subject vom Typ API_KEY über den createSubject-Endpunkt. Die Verbindung zwischen der Organisation vom Typ UNIT und dem API-Schlüssel wird über den X-Scope-Identifier hergestellt (unter Verwendung der id der 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"
      }'
    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"
    }
    }
  4. Token erstellen (UNIT)

    Erstellen Sie als Nächstes ein Token, das zur Erstellung von Ressourcen innerhalb der entsprechenden Organisation vom Typ UNIT verwendet 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"
      }'
    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"
    }
    }
  5. 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) oder INDIVIDUAL (natürliche Person) fest. In beiden Fällen müssen name und address angegeben werden.
    • Geben Sie innerhalb der französischen fiscalization-Informationen Folgendes an:
      • tax_id_number: Französische Unternehmensidentifikationsnummer (SIREN), ausgestellt von INSEE
      • credentials: Anmeldedaten für das französische Fiskalisierungsportal

    Nach der Erstellung wird der state des Steuerpflichtigen auf ACQUIRED gesetzt. Aktualisieren Sie ihn mit dem updateTaxpayer-Endpunkt auf COMMISSIONED.

    # 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"
      }'
  6. Standort erstellen

    Erstellen Sie für jeden operativen Geschäftsstandort einen Location vom Typ BRANCH über den createLocation-Endpunkt.

    Nach der Erstellung wird der state des Standorts auf ACQUIRED gesetzt. Aktualisieren Sie ihn mit dem updateLocation-Endpunkt auf COMMISSIONED.

    # 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"
      }'
  7. 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_DEVICE bereitgestellt werden.

    • Ein System wird mit einem spezifischen, zuvor erstellten Location vom Typ BRANCH verbunden.
    • Geben Sie für jedes Gerät Produktinformationen (MPN, Marke, Nutzungsbeginn) und Software-Details an.

    Nach der Erstellung wird der state des Systems auf ACQUIRED gesetzt. Aktualisieren Sie ihn mit dem updateSystem-Endpunkt auf COMMISSIONED.

    # 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"
      }'
  8. 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"
            }
          ]
        }
      }'

    Sobald der Datensatz ordnungsgemäß erstellt wurde, werden die Daten signiert, journalisiert und archiviert, um die drei wesentlichen Fiskalpflichten in Frankreich zu erfüllen.

Was this page helpful?