Para clientes de SIGN DE

⚠️ 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).

Guía de integración de SIGN FR para clientes de SIGN DE

Esta guía explica las diferencias clave respecto a SIGN DE y te ayuda a integrar con éxito la API de fiskaly SIGN FR. Describe todos los pasos necesarios para ti y sus comerciantes.

Enfoque de API Unificada

SIGN FR es parte del enfoque de API Unificada de fiskaly. Esto significa que al integrar SIGN FR, ya está preparado para usar SIGN IT (Italia) y SIGN ES (España), así como otros países próximos, con un esfuerzo adicional mínimo.

A diferencia de SIGN DE, SIGN FR no requiere una Management API independiente. Todos los endpoints necesarios para autenticación, creación de assets, configuración y manejo de registros fiscales están incluidos directamente en la API de SIGN FR, lo que hace la integración más rápida y sencilla.

Entornos: TEST y LIVE

En SIGN FR, hay dos URLs base separadas para los diferentes entornos:

Entorno TEST: https://test.api.fiskaly.com
Entorno LIVE: https://live.api.fiskaly.com

Esto es diferente de SIGN DE, donde hay solo una URL base para ambos entornos.
En SIGN DE, la Clave API en sí determina si se crean recursos TEST o LIVE.
Un token creado con una Clave API LIVE crea recursos LIVE.
Un token creado con una Clave API TEST crea recursos TEST — aunque la URL sea la misma.

En SIGN FR, el entorno se selecciona a través de la URL base.
Debe llamar a cada endpoint con la URL base correcta (test.api.fiskaly.com o live.api.fiskaly.com), dependiendo de si desea interactuar con el entorno TEST o LIVE.

Parámetros de encabezado

En el enfoque de API Unificada, se introdujeron algunos nuevos encabezados HTTP para simplificar sus procesos.
Proporcionan flexibilidad, garantizan la integridad de los datos y hacen que las integraciones sean más simples y confiables.

X-Api-Version

Para todas las soluciones de API Unificada, cada solicitud debe incluir el encabezado X-Api-Version.
El valor corresponde a la fecha de lanzamiento de la versión. Esto te da control total sobre cuándo cambiar a una versión más nueva para usar nuevas funciones.

Puede probar los cambios primero en el entorno TEST y solo migrar a la nueva versión una vez que todo se haya verificado. Esto también te permite mantener a algunos clientes en una versión anterior si es necesario mientras incorpora nuevos clientes directamente con la última versión.

Ventaja principal: no más cambios incompatibles en su versión en ejecución.

X-Idempotency-Key

Dado que los IDs de recursos ya no necesitan ser que tú defines sino que son generados por la API, el X-Idempotency-Key garantiza que una llamada a la API se maneje de manera idempotente.

Esto significa que las solicitudes idénticas repetidas con el mismo X-Idempotency-Key producen el mismo resultado y previenen creaciones duplicadas.

El X-Idempotency-Key es requerido para todas las solicitudes POST y PATCH.

X-Scope-Identifier

El encabezado X-Scope-Identifier reemplaza los parámetros de ruta utilizados anteriormente en la Management API para establecer relaciones entre recursos.

Hace que las integraciones sean más limpias y flexibles, ya que el encabezado define explícitamente el alcance (por ejemplo, a qué Asset::Unit pertenece una Clave API).

Mapeo de terminología: SIGN FR vs. SIGN DE

SIGN FR	SIGN DE	Explicación
`Asset::Tenant`	(sin equivalente)	Estructura de nivel superior en el fiskaly HUB. Representa toda la cuenta del cliente. No puede anidarse dentro de otros assets.
`Asset::Group` (opcional)	`organization` (con `billing_options`)	Capa intermedia opcional utilizada para organizar múltiples contribuyentes en grupos lógicos.
`Asset::Unit`	`managed_organization`	Representa a un comerciante o contribuyente individual. Cada `Asset::Unit` se vincula a un contribuyente a través de una `Entity`.
`Entity::COMPANY` o `Entity::INDIVIDUAL`	En Alemania parte de la `managed_organization` (DSFINVK DE) o `taxpayer` (SUBMIT DE)	Define el contribuyente para el `Asset::Unit` vinculado, requerido para cumplir con las obligaciones fiscales.
`Entity::LOCATION`	Comparable: `establishment` (SUBMIT DE)	Representa las ubicaciones físicas (p.ej. tiendas) operadas por el contribuyente.
`System::FISCAL_DEVICE`	`client`	Representa el sistema de caja / caja registradora utilizado para la fiscalización.
`Subject::API_KEY`	`API key`	Objeto de autenticación de clave API, utilizado para autorizar el acceso.
`Record`	`transaction`	Representa una operación realizada en la caja registradora. Para eventos especiales, puede consistir solo en una `Record::INTENTION`. Para transacciones, siempre requiere dos llamadas: una `Record::INTENTION` y una `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Marca el inicio de un proceso de compra, o un único evento que se procesa en la caja registradora.
`Record::TRANSACTION`	`Finish-Transaction`	Marca la finalización (fin) de un proceso de compra.

SIGN FR paso a paso

Primera organización

Para comenzar, debe crear una organización separada específicamente para Francia en el fiskaly HUB y una Clave API dedicada para la integración francesa.

A partir de este punto, todos los pasos de integración se gestionan directamente a través de la API de SIGN FR. A diferencia de SIGN DE, ya no necesita usar la Management API para crear o gestionar estructuras organizativas. Toda la funcionalidad requerida es parte de la API de SIGN FR misma.

POST: Crear Token

Use este token para autenticar la creación de la estructura organizativa para Francia.
Funciona de la misma manera que el token en SIGN DE (Management API), que se creaba usando la Clave API de la organización (principal) y luego se usaba para crear managed_organizations.
En SIGN FR, este token es ahora necesario para crear recursos Asset::Unit.

POST: Crear Asset (UNIT)

Crea un Asset::UNIT (Asset de tipo Unit) que representa a su primer cliente. Esto es equivalente a managed_organization creada a través de la Management API usada para SIGN DE.

En este paso, solo se requiere el nombre del Asset::Unit.
A diferencia de SIGN DE, la información del contribuyente pertenece al recurso Entity, que puede ser de tipo COMPANY o INDIVIDUAL, dependiendo de si el contribuyente es una persona jurídica o física. Definirá estos detalles en el paso Entity (COMPANY / INDIVIDUAL) a continuación.

POST: Crear Subject (Clave API)

Cada uno de tus clientes requiere su propia Clave API para crear recursos dentro de su ámbito Asset::Unit específico.
Por esta razón, se debe crear un Subject::API_KEY (Subject de tipo Clave API).

Vincula su Clave API al Asset::Unit usando el encabezado X-Scope-Identifier.

A diferencia de SIGN DE, la información sobre a qué Unit pertenece la Clave API ya no se proporciona a través del parámetro de ruta, sino a través del parámetro de encabezado X-Scope-Identifier.
Este encabezado debe contener el ID del Asset::UNIT al que pertenece la Clave API.

POST: Crear Token (con ámbito)

Este token tiene el ámbito del Asset::Unit. Úselo para todas las operaciones específicas del contribuyente.

Con la Clave API creada anteriormente para el Asset::Unit, debe crear este token con ámbito.
Se utilizará para todas las operaciones que necesiten gestionarse dentro de este Asset::Unit específico.

POST: Crear Entity (COMPANY / INDIVIDUAL)

Define la representación del contribuyente para el Asset::Unit correspondiente.

Una Entity de tipo COMPANY o INDIVIDUAL representa al contribuyente — ya sea una entidad jurídica (empresa) o una persona física (trabajador autónomo).
Cada contribuyente debe crearse como Entity antes de que puedan realizarse operaciones fiscales.

Como SIGN FR sigue el enfoque de API Unificada, la estructura Entity está diseñada de manera estandarizada y dividida en dos partes principales:

Información general (compartida entre todos los países):
Esto incluye atributos comunes como el nombre y la dirección del contribuyente.
Información de fiscalización (sección específica del país):
Contiene atributos fiscales requeridos por las normativas nacionales, como el número de identificación fiscal y las credenciales fiscales.
En Francia, esto incluye atributos fiscales como el número SIREN y la fecha del ejercicio fiscal que son requeridos por las regulaciones nacionales.

PATCH: Actualizar Entity

Actualiza el estado de ACQUIRED a COMMISSIONED para activar la Entity.

A diferencia de SIGN DE, las Entities en SIGN FR tienen un atributo de estado.
Cuando se crea una Entity, su estado inicial es ACQUIRED.
Antes de que pueda usarse, la Entity debe actualizarse al estado COMMISSIONED.

Este paso es irreversible. A partir de este momento, el recurso se vuelve facturable según el modelo de facturación aplicable.

Si una Entity ya no está en uso, puede actualizarse al estado DECOMMISSIONED.
Este paso también es irreversible y solo debe realizarse una vez que sea seguro que el cliente ya no usará esta Entity.

Además de los estados, cada Entity en SIGN FR tiene un atributo de modo que define su estado operativo.

Cuando la Entity está en estado ACQUIRED o DECOMMISSIONED, su modo es siempre INACTIVE.
En este modo, el recurso no puede usarse.
Cuando la Entity se actualiza al estado COMMISSIONED, el servicio SIGN FR valida automáticamente todas las configuraciones requeridas.
Si tiene éxito, el modo cambia a OPERATIVE.
Si hay un problema con la Entity o uno de sus recursos dependientes, el modo cambia automáticamente a DEGRADED hasta que se resuelva el problema.
Una vez resuelto el problema, el servicio SIGN FR devolverá el modo a OPERATIVE.
El modo SUSPENDED puede configurarse manualmente para Entities en estado COMMISSIONED usando el endpoint de actualización.
Esto es útil para pausar temporalmente las operaciones fiscales, por ejemplo, al actualizar credenciales o realizar mantenimiento.
Si el servicio SIGN FR establece la Entity en modo DEGRADED debido a un problema que requiere acción del usuario, el modo debe cambiarse primero a SUSPENDED mientras se realizan las acciones necesarias,
y luego actualizarse de nuevo a OPERATIVE una vez resuelto el problema.

Resumen:

INACTIVE: Modo predeterminado para ACQUIRED y DECOMMISSIONED
OPERATIVE: Modo productivo normal
DEGRADED: Establecido automáticamente por el servicio SIGN FR debido a un problema
SUSPENDED: Modo de mantenimiento manual

POST: Crear Entity (LOCATION)

Define la ubicación física del negocio. También comienza en estado ACQUIRED.

Para cada ubicación de un contribuyente, debe crearse una Entity separada de tipo LOCATION.
En la solución SIGN FR, esto no requiere un Asset::Unit separado.
Todas las ubicaciones de un contribuyente se representan dentro del mismo Asset::Unit y están vinculadas a la Entity::COMPANY o Entity::INDIVIDUAL correspondiente.
Cada contribuyente (Entity::COMPANY o Entity::INDIVIDUAL) debe tener al menos una Entity::LOCATION asociada.

PATCH: Actualizar Entity

Actualiza el estado de la Entity::LOCATION a COMMISSIONED.

Al igual que con Entity::COMPANY o Entity::INDIVIDUAL, la Entity::LOCATION también debe actualizarse al estado COMMISSIONED antes de que pueda usarse.
Solo después de este paso la ubicación se vuelve activa y puede usarse.

POST: Crear System

Un System de tipo FISCAL_DEVICE representa un sistema de caja o caja registradora.
Corresponde al client en SIGN DE.
Cada System está vinculado a una Entity::LOCATION.

A diferencia de SIGN DE, al crear un FISCAL_DEVICE, debe proporcionarse información adicional sobre el sistema de mantenimiento electrónico en sí.
La mayoría de estos detalles son típicamente definidos por el proveedor del sistema de caja.
En Alemania, esta información generalmente se agrega más tarde como parte del proceso DSFinV-K DE o Submit DE — en SIGN FR, sin embargo, esto se hace en un único paso durante la creación del sistema.

PATCH: Actualizar System

Actualiza el System del estado ACQUIRED a COMMISSIONED para activarlo.

El recurso System sigue la misma lógica de estado y modo que una Entity.
Una vez establecido en COMMISSIONED, el sistema se vuelve activo y la facturación se aplica automáticamente (cuando se usa en el entorno LIVE).
Si ya no está en uso, puede establecerse en DECOMMISSIONED, lo que — como en SIGN FR en general — es irreversible.

El atributo mode refleja la condición operativa del sistema (por ejemplo, OPERATIVE, SUSPENDED o DEGRADED).
Estos modos se comportan de la misma manera que se describe para Entity, lo que te permite suspender temporalmente las operaciones o indicar automáticamente un rendimiento degradado debido a problemas de configuración.

Configuración completada

Con el System comisionado con éxito, la fase de configuración inicial está completa.
Todas las estructuras organizativas y fiscales — desde Asset::Unit hasta Entity y System — están ahora activas y listas para producción.

A partir de este punto, los siguientes pasos describen las operaciones fiscales diarias realizadas en el sistema de caja.
Esto incluye la creación y el procesamiento de registros fiscales que representan ventas, devoluciones y otros eventos — equivalentes a transacciones en SIGN DE, pero con datos fiscales extendidos según se requiere en Francia.

Operaciones diarias en el sistema de caja

Una vez completada la configuración y comisionados todos los recursos, el proceso de fiscalización en SIGN FR continúa con las operaciones diarias.
Estas operaciones representan las actividades comerciales diarias en el sistema de caja — como emitir recibos, procesar devoluciones o gestionar cancelaciones.

Aunque el concepto general es similar a SIGN DE, SIGN FR introduce un modelo de Record unificado y más rico en datos.
Cada transacción se representa como uno o más Records, que son firmados digitalmente, registrados en el diario y archivados para garantizar el pleno cumplimiento fiscal.

Las siguientes secciones describen cómo crear, procesar y gestionar estos Records en el entorno fiscal francés.

POST: Crear Record

En SIGN FR, cada transacción fiscal se representa como uno o más Records.
Este modelo reemplaza el proceso de actualización de transacciones en dos pasos de SIGN DE (ACTIVE → FINISHED) con dos recursos independientes: un Record de tipo INTENTION y otro Record de tipo TRANSACTION.

Parte A) INTENTION

En SIGN DE, una transacción comienza con un evento Start-Transaction que marca el inicio de un proceso fiscal y se actualiza posteriormente a un estado finalizado.
En SIGN FR, esta lógica se reemplaza por un recurso dedicado: un Record de tipo INTENTION.

Un Record de tipo INTENTION marca el inicio de una operación fiscal o realiza directamente operaciones que solo requieren un único paso, como EVENT, EXPORT o DUPLICATE.
En Francia, las operaciones de intention admitidas son TRANSACTION, EVENT, EXPORT y DUPLICATE.

Contiene información contextual que define la intención de la operación, incluyendo:

El System (System::FISCAL_DEVICE) que realiza la operación.
El tipo de operación, correspondiente a una de las operaciones de intention admitidas mencionadas anteriormente.

Parte B) TRANSACTION

En SIGN DE, una transacción se finaliza a través de una actualización Finish-Transaction del recurso de transacción que completa el proceso fiscal.
En SIGN FR, este paso se representa mediante un recurso separado: un Record de tipo TRANSACTION.

Un Record de tipo TRANSACTION completa la operación fiscal y hace referencia al Record de tipo INTENTION creado anteriormente.
Contiene todos los datos fiscales y de transacción requeridos para la operación.
En comparación con SIGN DE, el alcance y la estructura de los datos son más amplios y están más estrechamente alineados con la información contenida en una transacción dentro de un cierre de punto de venta (Kassenabschluss) en DSFinV-K DE.

Incluye:

Información del documento como número de documento, fecha y montos totales brutos y netos.
Detalles para cada línea de venta (bienes o servicios), incluyendo descripción, cantidad, tipo de IVA e importe.
Referencias a recibos anteriores al crear registros CORRECTION o CANCELLATION.
También se admiten tipos de operación adicionales dentro de Record::TRANSACTION, según el proceso comercial y el contexto fiscal.

Este tipo de Record proporciona la representación fiscal completa de la transacción según lo exigido por la normativa francesa.

Estados y modos de Record

Cada Record en SIGN FR (ya sea INTENTION, TRANSACTION u otros tipos) sigue su propio estado y modo, que refleja su ciclo de vida dentro del proceso de fiscalización.

Estados

Accepted – El Record ha sido recibido, validado y está listo para su procesamiento.
Rejected – La validación ha fallado; los detalles están disponibles en los mensajes de registro.
Completad – El Record ha sido procesado con éxito.
Failed – El Record no pudo procesarse debido a un fallo en un componente externo.

Modos

Processing – El Record se está procesando actualmente.
Finished – El Record ha sido procesado, con éxito o sin él.

Transiciones

Transición	Descripción
POST → Accepted	El Record se crea y entra temporalmente en el estado `Accepted` si la validación tiene éxito, y procede inmediatamente al siguiente paso.
POST → Rejected	El Record falla la validación y pasa automáticamente a `Rejected`, proporcionando registros de error.
Accepted → Completad	Establecido automáticamente cuando el procesamiento finaliza con éxito.
Accepted → Failed	Establecido cuando el procesamiento falla debido a un componente externo.
Processing → Finished	Indica que el procesamiento ha sido completado, independientemente del éxito o fracaso.

Este diseño basado en eventos permite que cada operación fiscal sea rastreada independientemente — sin actualizar el mismo recurso — garantizando una pista de auditoría transparente e inmutable para cada transacción.

Operaciones adicionales (no transaccionales)

Más allá del flujo estándar INTENTION → TRANSACTION, SIGN FR también admite operaciones fiscales no transaccionales:

EVENT – Se usa para registrar eventos del sistema o de configuración (por ejemplo, modo de formación, operaciones de prueba o reinicios del sistema).
DUPLICATE – Crea un duplicado de un documento fiscal existente.
EXPORT – Genera una exportación de datos fiscales.

Estas operaciones se representan como Records de tipo INTENTION únicamente y no requieren un equivalente TRANSACTION.
Extienden la trazabilidad fiscal a todas las actividades relevantes del sistema de caja más allá de las transacciones de venta.

Resumen

En las operaciones diarias, SIGN FR reemplaza el simple flujo de transacciones “Inicio → Fin” de SIGN DE con un modelo de Record multi-recurso y orientado a eventos.
Cada operación — ya sea una venta, corrección, exportación u otro evento fiscal — se firma, registra en el diario y archiva individualmente, garantizando la trazabilidad completa y el cumplimiento de la legislación fiscal francesa.

Was this page helpful?