Integrazione passo dopo passo

Questa guida illustra l’intero processo di integrazione dell’API fiskaly SIGN FR per la conformità fiscale francese, utilizzando una combinazione del fiskaly HUB e di richieste API. Al termine, avrai un Sistema completamente funzionante con i Record firmati, archiviati in journal e conservati.

Prima di iniziare la configurazione, ecco cosa configurerai:

🏢

Organization

AccountGenerato da HUB
Entità di livello superiore in fiskaly HUB. Non può essere annidata all’interno di un altro Account.
GroupGenerato da HUB
Livello intermedio che organizza le Unit in cluster logici (ad es. uno per paese).
UnitGenerato da API
Merchant / Taxpayer che opera all’interno del Group.

🔑

API Key & Secret

Livello GroupGenerato da HUB
Generato in HUB per l’Organization GROUP. Utilizzato per autenticarsi nell’API SIGN FR al fine di creare Organization Unit e le relative API Key.
Livello UnitGenerato da API
Generato tramite API (endpoint createSubject) per l’Organization UNIT. Utilizzato per autenticarsi per tutte le chiamate operative a livello di Unit.

🧾

Taxpayer

Rappresentazione di una COMPANY o INDIVIDUAL registrata presso le autorità fiscali francesi.

📍

Location

HEAD_OFFICE
Creata automaticamente alla creazione del Taxpayer, condivide lo stesso UUID. Coincide con l’indirizzo legale.
BRANCH
Ogni negozio, punto vendita o altra sede operativa aziendale in cui si svolgono operazioni fiscali.

💻

System

FISCAL_DEVICE
Astrazione di un registratore di cassa utilizzato per registrare i dati delle transazioni in conformità con le normative fiscali francesi (NF525).

📄

Record

Ogni operazione commerciale effettuata nel System. Richiede due chiamate successive:

INTENTION
Identifica l’intenzione di registrare una transazione nel System.
TRANSACTION
Identifica una ricevuta fiscale emessa dal System.

Prerequisiti

📘Prima di iniziare

Hai bisogno di un Account fiskaly e dell’accesso al fiskaly HUB. Se non hai ancora un Account, registrati qui.

Avrai anche bisogno di uno strumento per effettuare richieste HTTP — ad esempio cURL (riga di comando), Postman o il tuo codice applicativo.

💡Ambienti TEST e LIVE

Le API Key generate nell’ambiente TEST creeranno risorse TEST, mentre quelle dell’ambiente LIVE creeranno risorse LIVE. Per ulteriori dettagli, consulta il nostro articolo sugli ambienti TEST e LIVE .

Flusso di lavoro dell’integrazione

Il diagramma seguente illustra il flusso di lavoro e mette in evidenza i passaggi essenziali necessari per completare con successo la tua integrazione. Ogni riquadro rimanda direttamente al corrispondente passaggio di configurazione qui sotto.

📘Importante

I passaggi contrassegnati in giallo devono essere completati direttamente sul HUB, mentre i passaggi rimanenti devono essere gestiti tramite l’API. Eseguire ogni azione nel contesto corretto è un passaggio importante verso un’integrazione di successo.

Configurazione passo dopo passo

Registrarsi su HUB
Inizia registrandoti sul fiskaly HUB.
La creazione di un Account fiskaly è il primo passo; successivamente puoi procedere con la configurazione della prima struttura organizzativa per la tua azienda e la generazione della tua API Key.
📘Video tutorial
Guarda il nostro video per una spiegazione passo dopo passo su come configurare il tuo Account e la tua prima Organizzazione.
Creare Account e Group
Continua creando il tuo Account e il primo Group tramite il HUB. Nell’API SIGN FR, il GROUP è uno strato intermedio obbligatorio all’interno del tuo ACCOUNT, utilizzato per organizzare le tue organizzazioni UNIT.
Creare una API Key
Il passo successivo è generare una API Key per la tua organizzazione tramite il HUB. Questa coppia di API Key e Secret è necessaria per creare le tue Organizzazioni di tipo UNIT (Passo 5).
⚠️Conserva le tue credenziali in modo sicuro
Il Secret API viene mostrato una sola volta. Assicurati di copiarlo e conservarlo in un luogo sicuro prima di chiudere la finestra di dialogo.
A partire dal passo successivo, utilizzerai la nostra API SIGN FR.

Creare un Token (Gestione)
Inizia a utilizzare l’API SIGN FR tramite l’endpoint createToken. Dovrai creare un token per autenticarti nei passaggi successivi.
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" }'
Risposta di esempio (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" } }

Creare l'Organizzazione UNIT

Continua creando un’Organizzazione di tipo UNIT tramite l’endpoint createOrganization. Dovrai creare un’Organizzazione UNIT per ciascuna delle tue rappresentazioni di contribuenti.

Quando crei un’Organizzazione di tipo UNIT, assicurati che sia associata all’Organizzazione di tipo GROUP precedentemente creata tramite il HUB. Per fare ciò, utilizza il token generato dalle API Key create per la tua Organizzazione di tipo GROUP. Questo riflette la struttura gerarchica in cui l’Organizzazione di tipo UNIT è annidata sotto la tua Organizzazione di tipo GROUP.

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();

Risposta di esempio (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"
  }
}

Creare un Subject API Key

Crea un Subject di tipo API_KEY tramite l’endpoint createSubject. Il collegamento tra l’Organizzazione di tipo UNIT e la API Key viene stabilito tramite il X-Scope-Identifier (utilizzando l’id dell’Organizzazione appena creata).

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;

Risposta di esempio (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"
  }
}

Creare un Token (UNIT)

Successivamente, crea un token che verrà utilizzato per creare risorse all’interno della corrispondente Organizzazione di tipo UNIT.

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();

Risposta di esempio (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"
  }
}

Creare il Contribuente

Ora sei pronto per creare le parti operative necessarie per la fiscalizzazione in Francia. Utilizza l’endpoint createTaxpayer per creare la rappresentazione di un contribuente:

Imposta il Contribuente come tipo COMPANY (persona giuridica) o INDIVIDUAL (persona fisica). In entrambi i casi, devono essere forniti name e address.
All’interno delle informazioni di fiscalization francesi, fornisci:
- tax_id_number: numero di identificazione aziendale francese (SIREN) rilasciato dall’INSEE
- credentials: credenziali del portale di fiscalizzazione francese

Una volta creato, lo state del Contribuente viene impostato su ACQUIRED. Aggiornalo a COMMISSIONED utilizzando l’endpoint updateTaxpayer.

# Create Taxpayer
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"
      }
    }
  }'

# Commission Taxpayer
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"
  }'

// Create Taxpayer
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();

// Commission Taxpayer
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",
    }),
  }
);

Creare un'Ubicazione

Per ogni sede operativa dell’attività, crea una Location di tipo BRANCH tramite l’endpoint createLocation.

Una volta creata, lo state della Location viene impostato su ACQUIRED. Aggiornalo a COMMISSIONED utilizzando l’endpoint updateLocation.

# Create Location
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"
    }
  }'

# Commission Location
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"
  }'

// Create Location
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();

// Commission Location
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",
    }),
  }
);

Creare un System

L’endpoint createSystem ti permette di creare un’astrazione di ogni dispositivo utilizzato per emettere scontrini. Ogni cassa registratrice o POS deve essere fornito come nuovo System di tipo FISCAL_DEVICE.

Un System sarà collegato a una Location di tipo BRANCH precedentemente creata.
Per ogni dispositivo, fornisci informazioni sul prodotto (MPN, marca, data di inizio utilizzo) e i dettagli del software.

Una volta creato, lo state del System viene impostato su ACQUIRED. Aggiornalo a COMMISSIONED utilizzando l’endpoint updateSystem.

# Create System
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"
      }
    }
  }'

# Commission System
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"
  }'

// Create System
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();

// Commission System
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",
    }),
  }
);

Creare un Record

La creazione di un Record in SIGN FR richiede due chiamate successive:

Parte A) INTENTION — all’inizio del processo di vendita
Parte B) TRANSACTION — dopo il processo di pagamento

# Part A) Create Record — 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"
    }
  }'

# Part B) Create Record — 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"
        }
      ]
    }
  }'

// Part A) Create Record — 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();

// Part B) Create Record — 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();

Una volta creato correttamente il record, i dati verranno firmati, archiviati in journal e conservati per adempiere ai tre obblighi fiscali chiave in Francia.

💡Automatizza la configurazione

Questa intera sequenza di richieste può essere integrata in una soluzione di provisioning “con un clic” che non richiede alcuna interazione manuale da parte dell’utente. I dettagli di implementazione dipendono da te.

Prossimi passi

Riferimento API SIGN FR

Documentazione API completa per l'endpoint SIGN FR — tutte le risorse, i parametri e le risposte.

Modalità di riproduzione offline

Scopri come gestire gli scenari offline e riprodurre le transazioni quando la connettività viene ripristinata.

Glossario

Termini chiave e definizioni per il sistema di conformità fiscale francese.

Guida HUB

Scopri come gestire organizzazioni, API Key e risorse tramite fiskaly HUB.

Was this page helpful?