Integración paso a paso

⚠️ Está viendo la documentación de la versión de API 2025-08-12. La versión más reciente es 2026-05-04. Los cambios clave incluyen terminología actualizada (Asset → Organization, Entity → Taxpayer/Location).

Para comenzar el proceso de integración, consulta las instrucciones detalladas paso a paso que se proporcionan aquí.

El diagrama adjunto ilustra el flujo de trabajo y resalta los pasos esenciales necesarios para completar con éxito tu integración, para la cual deberás utilizar nuestra SIGN FR.

Paso 1: Registro

Comienza registrándote en el HUB.

La creación de una cuenta de 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 su 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.

Paso 2: Creación de tu primera organización

Continúa creando tu primera organización mediante el HUB. Esta organización representará al proveedor del sistema de caja o al comerciante con tu propio sistema de caja.

Paso 3: Generación de la 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 primer Asset de tipo UNIT (Paso 5).

Ten en cuenta que 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 entornos TEST y LIVE.

A partir del siguiente paso, utilizará nuestra API de SIGN FR.

Paso 4: GESTIÓN - Creación de un Token

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.

Paso 5: GESTIÓN - Creación de un Asset (Estructura organizativa)

Continúa creando un Asset de tipo UNIT a través del endpoint createAsset. Deberás crear un Asset UNIT para cada una de las representaciones de sus contribuyentes.

Al crear su primer Asset de tipo UNIT, asegúrate de que esté asociado con el UUID de la primera organización que creó a través del HUB. Para ello, utiliza el token generado a partir de las claves API creadas en la primera organización. Esto refleja la estructura jerárquica donde la UNIT está anidada bajo la primera organización.

Paso 6: GESTIÓN - Creación de un Subject

Crea un Subject de tipo API_KEY a través del endpoint createSubject. La conexión entre el Asset UNIT y la Clave API se establece mediante el X-Scope-Identifier (usando el id del Asset recién creado).

Paso 7: GESTIÓN - Creación de un nuevo Token

A continuación, crea un token que se utilizará para crear recursos dentro del Asset UNIT correspondiente.

Paso 8: OPERACIÓN - Creación de una Entity (Representación del contribuyente)

Ahora está listo para comenzar a crear las partes operativas necesarias para la fiscalización en Francia. Para ello, utiliza el endpoint createEntity para crear la representación de un Contribuyente de la siguiente manera:

• Deberás establecer el Contribuyente como una Entity de tipo Company (empresa) o Individual (autónomo/empresario individual). En ambos casos, se deben proporcionar name y address.
• Dentro de la información de fiscalization francesa, se deben proporcionar los siguientes datos del contribuyente:
  • tax_id_number: Número de identificación de empresa francesa (número SIREN) emitido por INSEE,
  • credentials: Credenciales de fiscalización francesa.

Una vez que crea una Entity, ya sea de tipo Company o Individual, su state se establecerá en ACQUIRED. Para ser completamente funcional, el estado debe actualizarse a COMMISSIONED utilizando el endpoint updateEntity.

Paso 9: OPERACIÓN - Creación de una Entity de Ubicación

Para cada ubicación comercial operativa, debe crear una Entity de tipo Location a través del endpoint createEntity.

Cuando crea una Entity de tipo Location, su state se establece inicialmente en ACQUIRED. Para proceder, debe cambiar el estado a COMMISSIONED utilizando el endpoint updateEntity.

Paso 10: OPERACIÓN - Creación de un System (Representación del sistema de caja)

El endpoint createSystem te permite crear una abstracción de cada dispositivo que utiliza para emitir recibos. Esto significa que cada caja registradora o punto de venta debe proporcionarse como un nuevo System en SIGN FR. Para ello, se debe seleccionar el tipo de System FISCAL_DEVICE.

• Un System estará conectado a una Entity ya creada (ya sea de tipo Company o Individual, o una Ubicación específica si difiere de la dirección legal).
• Para cada dispositivo, deberás proporcionar información del producto como MPN, marca y la fecha de inicio de uso, junto con el nombre del software y la versión instalados en el dispositivo. Esta información garantiza el seguimiento adecuado de qué dispositivo está realizando transacciones fiscales.

Cuando crea un System, su estado inicial se establece en ACQUIRED. Para crear Registros, su state debe actualizarse a COMMISSIONED utilizando el endpoint updateSystem.

Paso 11: OPERACIÓN - Creación de un Registro

💡Tip

La creación de un Registro en SIGN FR requerirá en la mayoría de los casos dos llamadas sucesivas:

• Parte A) INTENTION - justo al comienzo del proceso de venta - Parte B) TRANSACTION - directamente después del proceso de pago

Operación de transacción

PARTE A) Intention

Para cada operación comercial de tipo RECEIPT realizada en la caja registradora o el sistema de caja, el endpoint createRecord de la API de SIGN FR se utilizará en dos llamadas: la primera para registrar la intención de iniciar una transacción, y la segunda para proporcionar los datos de la transacción.

Un Registro de tipo Intention contendrá la siguiente información:

• Asociación con un System que realizará la transacción.
• Operación de tipo Transaction: Esto significa que la operación que el System pretende realizar es registrar una transacción.

Parte B) Transaction

El paso final para emitir un recibo conforme en Francia es realizar otra llamada al endpoint createRecord, indicando un Registro de tipo Transaction.

Cualquier documento de Transaction estará asociado al identificador interno de un Registro de tipo Intention ya creado, y puede contener detalles para propósitos de formación (documentos emitidos en modo de formación o prueba).

La Transaction puede usarse para realizar una de las siguientes operaciones en Francia:

• RECEIPT: Esta operación contiene toda la información necesaria para la creación de un documento comercial de ventas en Francia:
  • Información del documento como número, código de actividad (si aplica), fecha de la transacción y totales del documento (incluido e impuestos excluidos)
  • Información de cada entrada o línea de artículo vendido en la operación:
    • Identificación de una Venta
    • Descripción
    • Indicación si es un bien o servicio
• CORRECTION: Este tipo de operación se usa para representar cualquier proceso de devolución realizado. Contiene los mismos datos que una operación de tipo RECEIPT, y adicionalmente:
  • id de referencia a un recibo ya creado (documento de transacción original)
• CANCELLATION: Esta operación se usa para invalidar una transacción completa. Para ello, se debe proporcionar el id de un registro previamente creado.

Operaciones adicionales

Además del flujo estándar Intention → Transaction, SIGN FR admite las siguientes operaciones:

• DUPLICATE
• EXPORT
• EVENT

Estas operaciones se crean como un Registro de tipo Intention (con la operación DUPLICATE, EXPORT o EVENT) y no requieren una llamada de Transaction posterior. Permiten que las actividades adicionales del sistema de caja sean firmadas, registradas en el diario y archivadas más allá del flujo de transacciones estándar.

---

En todos los casos, una vez que el registro se crea correctamente, los datos serán firmados, registrados en el diario y archivados para cumplir con las tres obligaciones fiscales clave en Francia.