Integración paso a paso

Esta guía te lleva a través del proceso completo de integración de la API de fiskaly SIGN FR para el cumplimiento fiscal francés, utilizando una combinación del fiskaly HUB y solicitudes API. Al finalizar, dispondráss de un sistema completamente funcional con registros firmados, journalizados y archivados.

Antes de comenzar la configuración, esto es lo que configurará:

🏢

Organization

AccountGenerado por HUB
Entidad de nivel superior en fiskaly HUB. No puede estar anidada dentro de otra Account.
GroupGenerado por HUB
Capa intermedia que organiza las Units en clústeres lógicos (p. ej. uno por país).
UnitGenerado por API
Merchant / Taxpayer que opera dentro del Group.

🔑

API Key & Secret

Nivel GroupGenerado por HUB
Generado en HUB para la Organization GROUP. Se usa para autenticarse en la API SIGN FR y crear Organization Units y sus API Keys.
Nivel UnitGenerado por API
Generado vía API (endpoint createSubject) para la Organization UNIT. Se usa para autenticarse en todas las llamadas operativas a nivel de Unit.

🧾

Taxpayer

Representación de una COMPANY o INDIVIDUAL registrada ante las autoridades fiscales francesas.

📍

Location

HEAD_OFFICE
Creada automáticamente al crear el Taxpayer, comparte el mismo UUID. Coincide con el domicilio legal.
BRANCH
Cada tienda, local u otra ubicación operativa donde se realizan operaciones fiscales.

💻

System

FISCAL_DEVICE
Abstracción de una caja registradora utilizada para registrar datos de transacciones conforme a la normativa fiscal francesa (NF525).

📄

Record

Cada operación comercial realizada en el System. Requiere dos llamadas sucesivas:

INTENTION
Identifica la intención de registrar una transacción en el System.
TRANSACTION
Identifica un recibo fiscal emitido por el System.

Requisitos previos

📘Antes de comenzar

Necesita una cuenta fiskaly y acceso al fiskaly HUB. Si aún no tiene una cuenta, regístrese aquí.

También necesitará una herramienta para realizar solicitudes HTTP — por ejemplo cURL (línea de comandos), Postman o su propio código de aplicación.

💡Entornos TEST y LIVE

Las claves API generadas en el entorno TEST crearán recursos TEST, mientras que las del entorno LIVE crearán recursos LIVE. Para más detalles, consulta nuestro artículo sobre los entornos TEST y LIVE .

Flujo de trabajo de integración

El diagrama a continuación ilustra el flujo de trabajo y destaca los pasos esenciales necesarios para completar con éxito tu integración. Cada elemento enlaza directamente con el paso de configuración correspondiente a continuación.

📘Importante

Los pasos marcados en amarillo deben completarse directamente en el HUB, mientras que los pasos restantes deben gestionarse a través de la API. Realizar cada acción en el contexto correcto es un paso importante hacia una integración exitosa.

Configuración paso a paso

Registrarse en el HUB
Comienza registrándote en el fiskaly HUB.
Crear una cuenta fiskaly es el primer paso, tras el cual puede proceder con la configuración de la primera estructura organizativa para su negocio y la generación de tu clave API.
📘Tutorial en vídeo
Eche un vistazo a nuestro vídeo para obtener una explicación paso a paso sobre cómo configurar tu cuenta y tu primera organización.
Crear cuenta y grupo
Continúa creando tu cuenta y su primer grupo utilizando el HUB. En la API de SIGN FR, el GROUP es una capa intermedia obligatoria dentro de su ACCOUNT, utilizada para organizar tus organizaciones UNIT.
Crear clave API
El siguiente paso es generar una clave API para tu organización a través del HUB. Este par de clave API y secreto es necesario para crear su(s) organización(es) de tipo UNIT (paso 5).
⚠️Guarda tus credenciales de forma segura
El secreto API solo se muestra una vez. Asegúrate de copiarlo y almacenarlo en un lugar seguro antes de cerrar el diálogo.
A partir del siguiente paso, comenzará a utilizar nuestra API de SIGN FR.

Crear token (gestión)
Comienza a utilizar la API de SIGN FR a través del endpoint createToken. Deberás crear un token para autenticarte en los pasos siguientes.
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" }'
Ejemplo de respuesta (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" } }

Crear organización UNIT

Continúa creando una organización de tipo UNIT a través del endpoint createOrganization. Deberás crear una organización UNIT para cada una de sus representaciones de contribuyente.

Al crear una organización de tipo UNIT, asegúrate de que esté asociada a la organización de tipo GROUP que creó anteriormente a través del HUB. Para ello, utiliza el token generado a partir de las claves API creadas para tu organización de tipo GROUP. Esto refleja la estructura jerárquica donde la organización de tipo UNIT está anidada bajo tu organización de 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();

Ejemplo de respuesta (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"
  }
}

Crear subject clave API

Crea un subject de tipo API_KEY a través del endpoint createSubject. La conexión entre la organización de tipo UNIT y la clave API se establece a través del X-Scope-Identifier (utilizando el id de la organización recién creada).

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;

Ejemplo de respuesta (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"
  }
}

Crear token (UNIT)

A continuación, crea un token que se utilizará para crear recursos dentro de la organización de tipo UNIT correspondiente.

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

Ejemplo de respuesta (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"
  }
}

Crear contribuyente

Ahora está listo para crear las partes operativas necesarias para la fiscalización en Francia. Utiliza el endpoint createTaxpayer para crear la representación de un contribuyente:

Establece el contribuyente como tipo COMPANY (entidad legal) o INDIVIDUAL (persona física). En ambos casos, deben proporcionarse el name y la address.
Dentro de la información de fiscalization francesa, proporciona:
- tax_id_number: número de identificación de empresa francesa (SIREN) emitido por el INSEE
- credentials: credenciales del portal de fiscalización francés

Una vez creado, el state del contribuyente se establece en ACQUIRED. Actualícelo a COMMISSIONED utilizando el 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",
    }),
  }
);

Crear ubicación

Para cada ubicación de negocio operativa, crea una Location de tipo BRANCH a través del endpoint createLocation.

Una vez creada, el state de la ubicación se establece en ACQUIRED. Actualícelo a COMMISSIONED utilizando el 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",
    }),
  }
);

Crear sistema

El endpoint createSystem te permite crear una abstracción de cada dispositivo que utiliza para emitir recibos. Cada caja registradora o POS debe proporcionarse como un nuevo System de tipo FISCAL_DEVICE.

Un sistema se conectará a una Location de tipo BRANCH específica, creada anteriormente.
Para cada dispositivo, proporciona información del producto (MPN, marca, fecha de inicio de uso) y detalles del software.

Una vez creado, el state del sistema se establece en ACQUIRED. Actualícelo a COMMISSIONED utilizando el 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",
    }),
  }
);

Crear registro

Crear un registro en SIGN FR requiere dos llamadas sucesivas:

Parte A) INTENTION — al inicio del proceso de venta
Parte B) TRANSACTION — después del proceso de pago

# 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 vez que el registro se ha creado correctamente, los datos serán firmados, journalizados y archivados para cumplir con las tres obligaciones fiscales clave en Francia.

💡Automatizar la configuración

Toda esta secuencia de solicitudes puede integrarse en una solución de aprovisionamiento “con un clic” que no requiere interacción manual del usuario. Los detalles de implementación dependen de ti.

Próximos pasos

Referencia de la API de SIGN FR

Documentación completa de la API del endpoint de SIGN FR — todos los recursos, parámetros y respuestas.

Modo de reproducción sin conexión

Aprenda a gestionar escenarios sin conexión y reproducir transacciones cuando se restaure la conectividad.

Glosario

Términos clave y definiciones para el sistema de cumplimiento fiscal francés.

Guía del HUB

Aprenda a gestionar organizaciones, claves API y recursos a través del fiskaly HUB.

Was this page helpful?