Frankreich Schnellstart

Dieser Schnellstart führt Sie durch die Erstellung Ihres ersten signierten Fiscalbelegs mit fiskaly SIGN FR und erfüllt die drei wichtigsten französischen Fiscalpflichten: Signierung, Journalisierung und Archivierung.

Voraussetzungen

• Ein fiskaly-Konto (Registrierung unter hub.fiskaly.com)
• Ein API-Schlüssel und -Secret für eine GROUP-Organisation in der TEST-Umgebung
• Informationen zum Steuerpflichtigen: Firmenname, SIREN-Nummer, Adresse

⚠️Zugangsdaten sicher aufbewahren

Ihr API-Secret wird nur einmal angezeigt. Speichern Sie es sofort an einem sicheren Ort.

Schritte

1. Authentifizieren

   cURLJavaScriptPythonJavaC#

   curl -X POST https://test.api.fiskaly.com/tokens \
     -H "Content-Type: application/json" \
     -H "X-Api-Version: 2026-02-03" \
     -H "X-Idempotency-Key: $(uuidgen)" \\
     -d '{
       "content": {
         "type": "API_KEY",
         "key": "YOUR_API_KEY",
         "secret": "YOUR_API_SECRET"
       }
     }'

   const BASE = "https://test.api.fiskaly.com";
   const API_VERSION = "2026-02-03";
   
   const authResp = await fetch(`${BASE}/tokens`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "X-Api-Version": API_VERSION,
       "X-Idempotency-Key": crypto.randomUUID(),
     },
     body: JSON.stringify({
       content: { type: "API_KEY", key: "YOUR_API_KEY", secret: "YOUR_API_SECRET" },
     }),
   });
   
   const auth = await authResp.json();
   const access_token = auth.content.authentication.bearer;
   const headers = {
     "Authorization": `Bearer ${access_token}`,
     "Content-Type": "application/json",
     "X-Api-Version": API_VERSION,
   };

   import requests, uuid
   
   BASE = "https://test.api.fiskaly.com"
   API_VERSION = "2026-02-03"
   
   auth = requests.post(f"{BASE}/tokens", json={
       "content": {"type": "API_KEY", "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET"}
   }, headers={"X-Api-Version": API_VERSION, "X-Idempotency-Key": str(uuid.uuid4())})
   
   access_token = auth.json()["content"]["authentication"]["bearer"]
   hdrs = {"Authorization": f"Bearer {access_token}", "X-Api-Version": API_VERSION}

   // POST https://test.api.fiskaly.com/tokens
   // Headers: X-Api-Version: 2026-02-03, X-Idempotency-Key: <uuid>
   // Body: {"content":{"type":"API_KEY","key":"...","secret":"..."}}

   using var client = new HttpClient();
   client.DefaultRequestHeaders.Add("X-Api-Version", "2026-02-03");
   client.DefaultRequestHeaders.Add("X-Idempotency-Key", Guid.NewGuid().ToString());
   var authResp = await client.PostAsJsonAsync(
       "https://test.api.fiskaly.com/tokens",
       new { content = new { type = "API_KEY", key = "YOUR_API_KEY", secret = "YOUR_API_SECRET" } });

   📘Note

   SIGN FR verwendet dieselbe API-Plattform wie SIGN IT. Alle Anfragen erfordern den X-Api-Version-Header. Schreiboperationen benötigen außerdem X-Idempotency-Key.

2. Organisation, Steuerpflichtigen, Standort und System erstellen

   Das Setup folgt demselben Muster wie SIGN IT — erstellen Sie eine UNIT-Organisation, dann einen Steuerpflichtigen, Standort und System und nehmen Sie jede Ressource in Betrieb:

   cURLJavaScriptPythonJavaC#

   # UNIT-Organisation erstellen
   curl -X POST https://test.api.fiskaly.com/organizations \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -H "X-Api-Version: 2026-02-03" \
     -H "X-Idempotency-Key: $(uuidgen)" \
     -d '{"content": {"type": "UNIT", "name": "My French Company"}}'
   
   # Subject-API-Schlüssel für die UNIT erstellen, erneut authentifizieren, dann:
   
   # Steuerpflichtigen erstellen
   curl -X POST https://test.api.fiskaly.com/taxpayers \
     -H "Authorization: Bearer ${UNIT_TOKEN}" \
     -H "Content-Type: application/json" \
     -H "X-Api-Version: 2026-02-03" \
     -H "X-Idempotency-Key: $(uuidgen)" \
     -d '{
       "content": {
         "type": "COMPANY",
         "name": {"legal": "Ma Societe SARL", "trade": "Ma Societe"},
         "address": {
           "line": {"type": "STREET_NUMBER", "street": "Rue de Rivoli", "number": "1"},
           "code": "75001", "city": "Paris", "country": "FR"
         },
         "fiscalization": {
           "type": "FR",
           "tax_id_number": "123456789",
           "credentials": {
             "type": "LNE",
             "properties": {"legal_form": "SARL", "naf_ape_code": "1071C", "social_capital": "50000"}
           }
         }
       }
     }'
   
   # Steuerpflichtigen in Betrieb nehmen, Standort erstellen + in Betrieb nehmen und System
   # (gleiches Muster wie SIGN IT — siehe vollständiges Integrationshandbuch)

   // UNIT-Organisation erstellen
   const org = await fetch(`${BASE}/organizations`, {
     method: "POST",
     headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
     body: JSON.stringify({ content: { type: "UNIT", name: "My French Company" } }),
   }).then(r => r.json());
   
   // Nach Erstellen des Subject-API-Schlüssels und erneuter Authentifizierung:
   
   // Steuerpflichtigen erstellen
   const taxpayer = await fetch(`${BASE}/taxpayers`, {
     method: "POST",
     headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
     body: JSON.stringify({
       content: {
         type: "COMPANY",
         name: { legal: "Ma Societe SARL", trade: "Ma Societe" },
         address: {
           line: { type: "STREET_NUMBER", street: "Rue de Rivoli", number: "1" },
           code: "75001", city: "Paris", country: "FR",
         },
         fiscalization: {
           type: "FR",
           tax_id_number: "123456789",
           credentials: {
             type: "LNE",
             properties: { legal_form: "SARL", naf_ape_code: "1071C", social_capital: "50000" },
           },
         },
       },
     }),
   }).then(r => r.json());
   
   // Steuerpflichtigen in Betrieb nehmen → Standort erstellen → in Betrieb nehmen → System erstellen → in Betrieb nehmen

   # Steuerpflichtigen erstellen (nach Org + Subject-Einrichtung)
   taxpayer = requests.post(f"{BASE}/taxpayers", headers={
       **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
   }, json={"content": {
       "type": "COMPANY",
       "name": {"legal": "Ma Societe SARL", "trade": "Ma Societe"},
       "address": {
           "line": {"type": "STREET_NUMBER", "street": "Rue de Rivoli", "number": "1"},
           "code": "75001", "city": "Paris", "country": "FR",
       },
       "fiscalization": {
           "type": "FR", "tax_id_number": "123456789",
           "credentials": {
               "type": "LNE",
               "properties": {"legal_form": "SARL", "naf_ape_code": "1071C", "social_capital": "50000"},
           },
       },
   }}).json()
   
   # In Betrieb nehmen, dann Standort + System erstellen und in Betrieb nehmen...

   // Gleiches Muster wie SIGN IT:
   // POST /organizations → UNIT
   // POST /subjects → API_KEY (bereichsbezogen)
   // POST /tokens → erneut authentifizieren
   // POST /taxpayers → FR fiscalization
   // PATCH /taxpayers/{id} → COMMISSIONED
   // POST /locations → BRANCH
   // POST /systems → FISCAL_DEVICE

   // Gleiches Muster wie SIGN IT — erstellen und in Betrieb nehmen:
   // Organisation → Steuerpflichtiger → Standort → System
   // Frankreich-spezifisch: fiscalization.type = "FR", tax_id_number = SIREN (9 Stellen)

3. Ersten Datensatz erstellen

   cURLJavaScriptPythonJavaC#

   # Teil A: Absicht
   curl -X POST https://test.api.fiskaly.com/records \
     -H "Authorization: Bearer ${UNIT_TOKEN}" \
     -H "Content-Type: application/json" \
     -H "X-Api-Version: 2026-02-03" \
     -H "X-Idempotency-Key: $(uuidgen)" \
     -d '{
       "content": {
         "type": "INTENTION",
         "system": {"id": "YOUR_SYSTEM_ID"},
         "operation": {"type": "TRANSACTION"}
       }
     }'
   
   # Teil B: Transaktion
   curl -X POST https://test.api.fiskaly.com/records \
     -H "Authorization: Bearer ${UNIT_TOKEN}" \
     -H "Content-Type: application/json" \
     -H "X-Api-Version: 2026-02-03" \
     -H "X-Idempotency-Key: $(uuidgen)" \
     -d '{
       "content": {
         "type": "TRANSACTION",
         "record": {"id": "INTENTION_ID"},
         "operation": {
           "type": "RECEIPT",
           "document": {
             "number": "0001",
             "total_vat": {
               "amount": "2.00",
               "exclusive": "10.00",
               "inclusive": "12.00"
             }
           },
           "entries": [{
             "type": "SALE",
             "details": {"concept": "GOOD"},
             "data": {
               "type": "ITEM",
               "text": "Product A",
               "unit": {
                 "quantity": "1.00",
                 "price": {"inclusive": "12.00", "exclusive": "10.00"}
               },
               "value": {"base": "10.00", "discount": "0.00"},
               "vat": {
                 "type": "VAT_RATE",
                 "code": "STANDARD",
                 "percentage": "20.00",
                 "exclusive": "10.00",
                 "inclusive": "12.00",
                 "amount": "2.00"
               }
             }
           }],
           "payments": [{"type": "CASH", "details": {"amount": "12.00"}}]
         }
       }
     }'

   // Teil A: Absicht
   const intention = await fetch(`${BASE}/records`, {
     method: "POST",
     headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
     body: JSON.stringify({
       content: {
         type: "INTENTION",
         system: { id: systemId },
         operation: { type: "TRANSACTION" },
       },
     }),
   }).then(r => r.json());
   
   // Teil B: Transaktion
   const record = await fetch(`${BASE}/records`, {
     method: "POST",
     headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
     body: JSON.stringify({
       content: {
         type: "TRANSACTION",
         record: { id: intention.content.id },
         operation: {
           type: "RECEIPT",
           document: {
             number: "0001",
             total_vat: { amount: "2.00", exclusive: "10.00", inclusive: "12.00" },
           },
           entries: [{
             type: "SALE",
             details: { concept: "GOOD" },
             data: {
               type: "ITEM",
               text: "Product A",
               unit: { quantity: "1.00", price: { inclusive: "12.00", exclusive: "10.00" } },
               value: { base: "10.00", discount: "0.00" },
               vat: {
                 type: "VAT_RATE", code: "STANDARD", percentage: "20.00",
                 exclusive: "10.00", inclusive: "12.00", amount: "2.00",
               },
             },
           }],
           payments: [{ type: "CASH", details: { amount: "12.00" } }],
         },
       },
     }),
   }).then(r => r.json());
   
   console.log("Datensatz erstellt und archiviert:", record.content.state);

   # Teil A: Absicht
   intention = requests.post(f"{BASE}/records", headers={
       **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
   }, json={"content": {
       "type": "INTENTION", "system": {"id": system_id},
       "operation": {"type": "TRANSACTION"},
   }}).json()
   
   # Teil B: Transaktion
   record = requests.post(f"{BASE}/records", headers={
       **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
   }, json={"content": {
       "type": "TRANSACTION", "record": {"id": intention["content"]["id"]},
       "operation": {
           "type": "RECEIPT",
           "document": {"number": "0001",
               "total_vat": {"amount": "2.00", "exclusive": "10.00", "inclusive": "12.00"}},
           "entries": [{"type": "SALE", "details": {"concept": "GOOD"}, "data": {
               "type": "ITEM", "text": "Product A",
               "unit": {"quantity": "1.00", "price": {"inclusive": "12.00", "exclusive": "10.00"}},
               "value": {"base": "10.00", "discount": "0.00"},
               "vat": {"type": "VAT_RATE", "code": "STANDARD", "percentage": "20.00",
                   "exclusive": "10.00", "inclusive": "12.00", "amount": "2.00"}}}],
           "payments": [{"type": "CASH", "details": {"amount": "12.00"}}],
       },
   }}).json()

   // POST /records → INTENTION (system.id, operation.type = TRANSACTION)
   // POST /records → TRANSACTION (record.id = intention ID, Kassenbondaten mit Einträgen)
   // Daten werden signiert, journalisiert und für NF525-Konformität archiviert

   // Zweistufige Datensatzerstellung: INTENTION → TRANSACTION
   // Französischer Mehrwertsteuersatz: 20,00 % (Standardsatz)
   // Antwort bestätigt Signierung, Journalisierung und Archivierung

   Nach der Erstellung werden die Daten automatisch signiert, journalisiert und archiviert — erfüllt damit die drei wesentlichen NF525-Fiscalpflichten.

Nächste Schritte

Vollständiges Integrationshandbuch

Vollständige Schritt-für-Schritt-Anleitung mit allen 11 Schritten

Kernfunktionalitäten

Signierungs-, Journalisierungs- und Archivierungsfähigkeiten

Offline-Modus

Kassensystem bei Ausfällen am Laufen halten