Para clientes de SIGN DE

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 forma parte del enfoque de API Unificada de fiskaly. Esto significa que al integrar SIGN FR, ya está preparado para utilizar 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 separada. Todos los endpoints necesarios para la autenticación, creación de organizaciones, configuración y gestión de registros fiscales se incluyen directamente en SIGN FR, lo que hace que la integración sea más rápida y sencilla.

Entornos: TEST y LIVE

En SIGN FR, hay dos URL 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 utilizada para ambos entornos.
En SIGN DE, la propia clave API 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 mediante 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 cabecera

En el enfoque de API Unificada, se introdujeron algunas nuevas cabeceras HTTP para simplificar sus procesos.
Proporcionan flexibilidad, garantizan la integridad de los datos y hacen que las integraciones sean más sencillas y fiables.

X-Api-Version

Para todas las soluciones de API Unificada, cada solicitud debe incluir la cabecera X-Api-Version.
El valor corresponde a la fecha de publicación de la versión. Esto te da control total sobre cuándo cambiar a una versión más reciente para utilizar nuevas funcionalidades.

Puede probar los cambios primero en el entorno TEST y solo migrar a la nueva versión una vez que todo haya sido verificado. Esto también te permite mantener a algunos clientes en una versión anterior mientras incorpora nuevos clientes directamente con la versión más reciente.

Principal ventaja: no más cambios disruptivos en su versión en producció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 gestiona de forma idempotente.

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

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

X-Scope-Identifier

La cabecera 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 la cabecera define explícitamente el ámbito (por ejemplo, a qué Organization::Unit pertenece una clave API).

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

SIGN FR	SIGN DE	Explicación
`Organization::ACCOUNT`	(sin equivalente)	Estructura de nivel superior en el fiskaly HUB. Representa toda la cuenta del cliente.
`Organization::GROUP`	`organization` (con `billing_options`)	Representa la organización principal, bajo la cual se anidan los contribuyentes
`Organization::UNIT`	`managed_organization`	Representa a un comerciante o contribuyente individual. Cada `Organization::UNIT` está vinculada a un `Taxpayer`.
`Taxpayer::COMPANY` or `Taxpayer::INDIVIDUAL`	En Alemania, parte de la `managed_organization` (DSFINVK DE) o `taxpayer` (SUBMIT DE)	Define al contribuyente para la `Organization::UNIT` vinculada, necesario para cumplir las obligaciones fiscales.
`Location`	Comparable: `establishment` (SUBMIT DE)	Representa ubicaciones físicas (p. ej., tiendas) operadas por el contribuyente.
`System::FISCAL_DEVICE`	`client`	Representa el POS / 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. 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.
`Record::TRANSACTION`	`Finish-Transaction`	Marca la finalización 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 SIGN FR. A diferencia de SIGN DE, ya no necesita utilizar la Management API para crear o gestionar estructuras organizativas. Toda la funcionalidad necesaria forma parte de la propia API de SIGN FR.

POST: Crear token

Utiliza 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 creó utilizando la clave API de la organización (principal) y luego se utilizó para crear managed_organizations.
En SIGN FR, este token es ahora necesario para crear recursos Organization::UNIT.

POST: Crear organización (UNIT)

Crea una Organization::UNIT (organización de tipo Unit) que represente a su primer cliente. Esto es equivalente a la managed_organization creada a través de la Management API utilizada para SIGN DE.

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

POST: Crear subject (clave API)

Cada uno de tus clientes necesita su propia clave API para crear recursos dentro de su ámbito específico de Organization::UNIT.
Por esta razón, debe crearse un Subject::API_KEY (subject de tipo API Key).

Vincula tu clave API a la Organization::UNIT utilizando la cabecera X-Scope-Identifier.

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

POST: Crear token (con ámbito)

Este token tiene como ámbito la Organization::UNIT. Úselo para todas las operaciones específicas del contribuyente.

Con la clave API creada anteriormente para la Organization::UNIT, debe crear este token con ámbito.
Se utilizará para todas las operaciones que deban gestionarse dentro de esta Organization::UNIT específica.

POST: Crear contribuyente (COMPANY / INDIVIDUAL)

Define la representación del contribuyente para la Organization::UNIT correspondiente.

Un Taxpayer de tipo COMPANY o INDIVIDUAL representa al contribuyente — ya sea una entidad legal (empresa) o una persona física (autónomo).
Cada contribuyente debe ser creado antes de que puedan realizarse operaciones fiscales.

Dado que SIGN FR sigue el enfoque de API Unificada, la estructura Taxpayer está diseñada de manera estandarizada y se divide en dos partes principales:

Información general (compartida en todos los países):
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 la normativa nacional, 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 la normativa nacional.

PATCH: Actualizar contribuyente

Actualiza el estado de ACQUIRED a COMMISSIONED para activar el contribuyente.

A diferencia de SIGN DE, los contribuyentes en SIGN FR tienen un atributo de estado.
Cuando se crea un contribuyente, su estado inicial es ACQUIRED.
Antes de que pueda utilizarse, el contribuyente debe actualizarse al estado COMMISSIONED.

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

Si un contribuyente ya no está en uso, puede actualizarse al estado DECOMMISSIONED.
Este paso también es irreversible y solo debe realizarse cuando se tenga la certeza de que el cliente ya no utilizará este contribuyente.

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

Cuando el contribuyente está en estado ACQUIRED o DECOMMISSIONED, su modo siempre es INACTIVE.
En este modo, el recurso no puede utilizarse.
Cuando el contribuyente se actualiza al estado COMMISSIONED, el servicio SIGN FR valida automáticamente todas las configuraciones requeridas.
Si es exitoso, el modo cambia a OPERATIVE.
Si hay un problema con el contribuyente 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 establecerse manualmente para contribuyentes en estado COMMISSIONED utilizando 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 el contribuyente 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 ubicación

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

Para cada ubicación de un contribuyente, debe crearse una Location separada.
En la solución SIGN FR, esto no requiere una Organization::UNIT separada.
Todas las ubicaciones de un contribuyente se representan dentro de la misma Organization::UNIT y están vinculadas al Taxpayer::COMPANY o Taxpayer::INDIVIDUAL correspondiente.
Cada contribuyente debe tener al menos una Location asociada.

PATCH: Actualizar ubicación

Actualiza el estado de la Location a COMMISSIONED.

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

POST: Crear sistema

Un System de tipo FISCAL_DEVICE representa un POS o caja registradora.
Corresponde al cliente en SIGN DE.
Cada System está vinculado a una Location.

A diferencia de SIGN DE, al crear un FISCAL_DEVICE, debe proporcionarse información adicional sobre el sistema de registro electrónico en sí.
La mayoría de estos detalles suelen ser definidos por el proveedor del POS.
En Alemania, esta información generalmente se añade posteriormente como parte del proceso DSFinV-K DE o Submit DE — en SIGN FR, sin embargo, esto se hace en un solo paso durante la creación del sistema.

PATCH: Actualizar sistema

Actualiza el System del estado ACQUIRED a COMMISSIONED para activarlo.

El recurso System sigue la misma lógica de estados y modos que un Taxpayer.
Una vez establecido en COMMISSIONED, el sistema se activa y la facturación se aplica automáticamente (cuando se utiliza en el entorno LIVE).
Si ya no está en uso, puede establecerse en DECOMMISSIONED, que — como en SIGN FR en general — es irreversible.

El atributo mode refleja el estado operativo del sistema (por ejemplo, OPERATIVE, SUSPENDED o DEGRADED).
Estos modos se comportan de la misma manera que se describe para Taxpayer, 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 Organization::UNIT hasta Taxpayer y System — ahora están activas y listas para producción.

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

Operaciones diarias en el POS

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 POS — como la emisión de recibos, el procesamiento de devoluciones o la gestión de cancelaciones.

Si bien el concepto general es similar a SIGN DE, SIGN FR introduce un modelo de registro unificado y con más datos.
Cada transacción se representa como uno o más Registros, que se firman digitalmente, se registran en el diario y se archivan para garantizar el pleno cumplimiento fiscal.

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

POST: Crear registro

En SIGN FR, cada transacción fiscal se representa como uno o más Registros.
Este modelo reemplaza el proceso de actualización de transacciones en dos pasos de SIGN DE (ACTIVE → FINISHED) con dos recursos independientes: un registro de tipo INTENTION y otro 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 posteriormente se actualiza a un estado finalizado.
En SIGN FR, esta lógica se reemplaza por un recurso dedicado: un registro de tipo INTENTION.

Un registro 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 intención admitidas son TRANSACTION, EVENT, EXPORT y DUPLICATE.

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

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

Parte B) TRANSACTION

En SIGN DE, una transacción se finaliza mediante una actualización Finish-Transaction del recurso de transacción que completa el proceso fiscal.
En SIGN FR, este paso está representado por un recurso separado: un registro de tipo TRANSACTION.

Un registro de tipo TRANSACTION completa la operación fiscal y hace referencia al registro de tipo INTENTION creado anteriormente.
Contiene todos los datos fiscales y transaccionales 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 caja (Kassenabschluss) en DSFinV-K DE.

Incluye:

Información del documento, como número de documento, fecha e importes totales brutos y netos.
Detalles de 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 empresarial y el contexto fiscal.

Este tipo de registro proporciona la representación fiscal completa de la transacción requerida por la regulación francesa.

Estados y modos de los registros

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

Estados

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

Modos

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

Transiciones

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

Este diseño basado en eventos permite rastrear cada operación fiscal de forma independiente — 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 utiliza 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 solo como registros de tipo INTENTION y no requieren una contraparte TRANSACTION.
Amplían la trazabilidad fiscal a todas las actividades relevantes del POS 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 registro 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 ley fiscal francesa.

Was this page helpful?