Avvio rapido Francia

Questa guida rapida ti accompagna nella creazione del tuo primo record fiscale firmato con fiskaly SIGN FR, adempiendo ai tre principali obblighi fiscali francesi: firma, registrazione e archiviazione.

Prerequisiti

• Un account fiskaly (registrati su hub.fiskaly.com)
• Una chiave API e un segreto per un’organizzazione GROUP nell’ambiente di TEST
• Informazioni sul contribuente: ragione sociale, numero SIREN, indirizzo

⚠️Conserva le credenziali in modo sicuro

Il tuo segreto API viene mostrato una sola volta. Salvalo immediatamente in un luogo sicuro.

Passaggi

1. Autenticarsi

   cURLJavaScriptPythonJavaC#

   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"
       }
     }'

   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,
     },
     body: JSON.stringify({
       content: { type: "API_KEY", key: "YOUR_API_KEY", secret: "YOUR_API_SECRET" },
     }),
   });
   
   const { access_token } = await authResp.json();
   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})
   
   access_token = auth.json()["access_token"]
   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
   // Body: {"content":{"type":"API_KEY","key":"...","secret":"..."}}

   using var client = new HttpClient();
   client.DefaultRequestHeaders.Add("X-Api-Version", "2026-02-03");
   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 usa la stessa piattaforma API di SIGN IT. Tutte le richieste richiedono l’intestazione X-Api-Version. Le operazioni di scrittura richiedono anche X-Idempotency-Key.

2. Creare Organizzazione, Contribuente, Sede e Sistema

   La configurazione segue lo stesso schema di SIGN IT — crea un’organizzazione UNIT, poi un Contribuente, Sede e Sistema, mettendo in servizio ogni risorsa:

   cURLJavaScriptPythonJavaC#

   # Creare Organizzazione UNIT
   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"}}'
   
   # Creare chiave API Soggetto per la UNIT, autenticarsi nuovamente, poi:
   
   # Creare Contribuente
   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"},
         "address": {"street": "1 Rue de Rivoli", "zip": "75001", "city": "Paris", "country_code": "FR"},
         "fiscalization": {
           "type": "FR",
           "tax_id_number": "123456789"
         }
       }
     }'
   
   # Mettere in servizio Contribuente, creare + mettere in servizio Sede e Sistema
   # (stesso schema di SIGN IT — consulta la guida di integrazione completa)

   // Creare Organizzazione UNIT
   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());
   
   // Dopo aver creato la chiave API Soggetto e autenticato nuovamente:
   
   // Creare Contribuente
   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" },
         address: { street: "1 Rue de Rivoli", zip: "75001", city: "Paris", country_code: "FR" },
         fiscalization: { type: "FR", tax_id_number: "123456789" },
       },
     }),
   }).then(r => r.json());
   
   // Mettere in servizio Contribuente → creare Sede → mettere in servizio → creare Sistema → mettere in servizio

   # Creare Contribuente (dopo configurazione org + soggetto)
   taxpayer = requests.post(f"{BASE}/taxpayers", headers={
       **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
   }, json={"content": {
       "type": "COMPANY",
       "name": {"legal": "Ma Societe SARL"},
       "address": {"street": "1 Rue de Rivoli", "zip": "75001", "city": "Paris", "country_code": "FR"},
       "fiscalization": {"type": "FR", "tax_id_number": "123456789"},
   }}).json()
   
   # Mettere in servizio, poi creare + mettere in servizio Sede e Sistema...

   // Stesso schema di SIGN IT:
   // POST /organizations → UNIT
   // POST /subjects → API_KEY (con ambito)
   // POST /tokens → autenticarsi nuovamente
   // POST /taxpayers → FR fiscalization
   // PATCH /taxpayers/{id} → COMMISSIONED
   // POST /locations → BRANCH
   // POST /systems → FISCAL_DEVICE

   // Stesso schema di SIGN IT — creare e mettere in servizio:
   // Organizzazione → Contribuente → Sede → Sistema
   // Specifico della Francia: fiscalization.type = "FR", tax_id_number = SIREN (9 cifre)

3. Creare il primo Record

   cURLJavaScriptPythonJavaC#

   # Parte A: Intenzione
   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"}
       }
     }'
   
   # Parte B: Transazione
   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",
         "intention": {"id": "INTENTION_ID"},
         "operation": {
           "type": "RECEIPT",
           "document": {
             "number": "1",
             "date": "2026-02-27",
             "amounts": {
               "total_including_vat": "12.00",
               "total_excluding_vat": "10.00"
             }
           },
           "entries": [{
             "type": "SALE",
             "description": "Product A",
             "nature": "GOOD",
             "quantity": "1",
             "amounts": {
               "unit_including_vat": "12.00",
               "total_including_vat": "12.00",
               "total_excluding_vat": "10.00",
               "vat": {"rate": "20.00", "amount": "2.00"}
             }
           }]
         }
       }
     }'

   // Parte A: Intenzione
   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());
   
   // Parte B: Transazione
   const record = await fetch(`${BASE}/records`, {
     method: "POST",
     headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
     body: JSON.stringify({
       content: {
         type: "TRANSACTION",
         intention: { id: intention.id },
         operation: {
           type: "RECEIPT",
           document: {
             number: "1", date: "2026-02-27",
             amounts: { total_including_vat: "12.00", total_excluding_vat: "10.00" },
           },
           entries: [{
             type: "SALE", description: "Product A", nature: "GOOD", quantity: "1",
             amounts: {
               unit_including_vat: "12.00", total_including_vat: "12.00",
               total_excluding_vat: "10.00",
               vat: { rate: "20.00", amount: "2.00" },
             },
           }],
         },
       },
     }),
   }).then(r => r.json());
   
   console.log("Record creato e archiviato:", record.state);

   # Parte A: Intenzione
   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()
   
   # Parte B: Transazione
   record = requests.post(f"{BASE}/records", headers={
       **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
   }, json={"content": {
       "type": "TRANSACTION", "intention": {"id": intention["id"]},
       "operation": {
           "type": "RECEIPT",
           "document": {"number": "1", "date": "2026-02-27",
               "amounts": {"total_including_vat": "12.00", "total_excluding_vat": "10.00"}},
           "entries": [{"type": "SALE", "description": "Product A", "nature": "GOOD",
               "quantity": "1", "amounts": {
                   "unit_including_vat": "12.00", "total_including_vat": "12.00",
                   "total_excluding_vat": "10.00", "vat": {"rate": "20.00", "amount": "2.00"}}}],
       },
   }}).json()

   // POST /records → INTENTION (system.id, operation.type = TRANSACTION)
   // POST /records → TRANSACTION (intention.id, dati dello scontrino con voci)
   // I dati vengono firmati, registrati e archiviati per la conformità NF525

   // Creazione record in due fasi: INTENTION → TRANSACTION
   // Aliquota IVA francese: 20,00% (standard)
   // La risposta conferma firma, registrazione e archiviazione

   Una volta creati, i dati vengono automaticamente firmati, registrati e archiviati — adempiendo ai tre obblighi fiscali chiave di NF525.

Prossimi passi

Guida all'integrazione completa

Guida completa passo dopo passo con tutti gli 11 passaggi

Funzionalità principali

Capacità di firma, registrazione e archiviazione

Modalità offline

Mantieni il tuo sistema di cassa attivo durante i guasti