Para Clientes 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 principales incluyen terminología actualizada (Asset → Organization, Entity → Taxpayer/Location).

Guía de Integración de SIGN IT para Clientes SIGN DE

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

Enfoque de API Unificada

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

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

Entornos: TEST y LIVE

En SIGN IT, existen dos URLs base separadas para los diferentes entornos:

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

Esto difiere de SIGN DE, donde existe una única URL base utilizada para ambos entornos.
En SIGN DE, la propia API Key determina si se crean recursos TEST o LIVE.
Un token creado con una API Key LIVE crea recursos LIVE.
Un token creado con una API Key TEST crea recursos TEST — aunque la URL permanezca igual.

En SIGN IT, 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 nuevas cabeceras HTTP para simplificar sus procesos.
Proporcionan flexibilidad, garantizan la integridad de los datos y hacen las integraciones 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 lanzamiento de la versión. Esto te da control total sobre cuándo cambiar a una versión más reciente para utilizar nuevas funciones.

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 si es necesario, mientras incorpora nuevos clientes directamente con la última versión.

Principal ventaja: no más cambios de ruptura 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 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 las integraciones más limpias y flexibles, ya que la cabecera define explícitamente el ámbito (por ejemplo, a qué Asset::UNIT pertenece una API Key).

Mapeo de Terminología: SIGN IT vs. SIGN DE

SIGN IT	SIGN DE	Explicación
`Asset::TENANT`	(sin equivalente)	Estructura de nivel superior en fiskaly HUB. Representa la cuenta completa del cliente. No puede anidarse dentro de otros assets.
`Asset::GROUP` (opcional)	`organisation` (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, necesario para cumplir con las obligaciones fiscales.
`Entity::LOCATION`	Comparable: `establishment` (SUBMIT DE)	Representa ubicaciones físicas (por ejemplo, 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 API Key, utilizado para autorizar el acceso.
`Record`	`transaction`	Representa una operación realizada en la caja registradora. Siempre requiere dos llamadas: un `Record::INTENTION` y un `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Marca el inicio de un proceso de compra, u otro evento individual procesado en la caja registradora.
`Record::TRANSACTION`	`Finish-Transaction`	Marca la finalización (fin) de un proceso de compra.

SIGN IT Paso a Paso

Primera Organización

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

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

POST: Crear Token

Utiliza este token para autenticar la creación de la estructura organizativa para Italia.
Funciona de la misma manera que el token en SIGN DE (Management API), que se creaba usando la API Key de la organización (principal) y luego se utilizaba para crear managed_organizations.
En SIGN IT, este token ahora es necesario para crear recursos Asset::UNIT.

POST: Crear Asset (UNIT)

Crea un Asset::UNIT (Asset de tipo Unit) que represente a su primer cliente. Esto es equivalente a managed_organization creado a través de la Management utilizada 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 natural. 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 API Key para crear recursos dentro de su ámbito específico Asset::UNIT.
Por ello, se debe crear un Subject::API_KEY (Subject de tipo API Key).

Vincula tu API Key al Asset::UNIT utilizando la cabecera X-Scope-Identifier.

A diferencia de SIGN DE, la información sobre a qué Unit pertenece la API Key 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 del Asset::UNIT al que pertenece la API Key.

POST: Crear Token (con ámbito)

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

Con la API Key creada anteriormente para el Asset::UNIT, debe crear este token con ámbito.
Se utilizará para todas las operaciones que deban realizarse 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 (autónomo).
Cada contribuyente debe crearse como Entity antes de poder realizar operaciones fiscales.

Dado que SIGN IT sigue el enfoque de API Unificada, la estructura Entity está diseñada de forma estandarizada y dividida en dos partes principales:

Información general (compartida entre 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 de cada país):
Contiene atributos fiscales requeridos por las regulaciones nacionales, como el número de identificación fiscal y las credenciales fiscales.
En Italia, esto incluye atributos fiscales como el número fiscal (Codice Fiscale) y el número de IVA (Partita IVA) 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 IT tienen un atributo state.
Cuando se crea una Entity, su estado inicial es ACQUIRED.
Antes de poder utilizarse, la Entity debe actualizarse al estado COMMISSIONED.

Este paso es irreversible. A partir de este punto, el recurso pasa a ser 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 cuando sea seguro que el cliente ya no utilizará esta Entity.

Además de los estados, cada Entity en SIGN IT tiene un atributo mode 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 utilizarse.
Cuando la Entity se actualiza al estado COMMISSIONED, el servicio SIGN IT 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 (aún no implementado) hasta que se resuelva el problema.
Una vez resuelto el problema, el servicio SIGN IT devolverá el modo a OPERATIVE.
El modo SUSPENDED puede establecerse manualmente para Entities en estado COMMISSIONED utilizando el endpoint updateEntity.
Esto es útil para pausar temporalmente las operaciones fiscales, por ejemplo, al actualizar credenciales o realizar mantenimiento. Si el servicio SIGN IT establece la Entity en modo DEGRADED (aún no implementado) debido a un problema que requiere la intervención del usuario, el modo debe cambiarse primero a SUSPENDED mientras se realizan las acciones necesarias, y luego volver a OPERATIVE una vez resuelto el problema.

Resumen:

INACTIVE: Modo predeterminado para ACQUIRED y DECOMMISSIONED
OPERATIVE: Modo productivo normal
DEGRADED (aún no implementado): Establecido automáticamente por el servicio SIGN IT 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, se debe crear una Entity separada de tipo LOCATION.
En la solución SIGN IT, esto no requiere un Asset::UNIT separado.
Todas las ubicaciones de un contribuyente se representan dentro del mismo Asset::UNIT y se vinculan 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 (LOCATION)

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 poder utilizarse.
Solo después de este paso la ubicación se activa y puede utilizarse.

POST: Crear System

Un System de tipo FISCAL_DEVICE representa un POS 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, se debe proporcionar 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 agrega más tarde como parte del proceso de DSFinV-K DE o Submit DE — en SIGN IT, sin embargo, esto se realiza 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 activa 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 IT en general — es irreversible.

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

Configuración Completada

Con el System puesto en marcha exitosamente, 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 POS.
Esto incluye la creación y 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 lo requerido en Italia.

Operaciones Diarias en el POS

Una vez completada la configuración y todos los recursos puestos en marcha, el proceso de fiscalización en SIGN IT 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.

Aunque el concepto general es similar a SIGN DE, SIGN IT introduce un modelo de Registro unificado y más rico en 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 italiano.

POST: Crear Registro

En SIGN IT, 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 luego se actualiza a un estado finalizado.
En SIGN IT, 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.
En Italia, la operación de intención admitida es TRANSACTION.

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 la TRANSACTION.

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 IT, este paso se representa mediante un recurso separado: un Registro de tipo TRANSACTION.

Un Registro de tipo TRANSACTION completa la operación fiscal y referencia el Registro de tipo INTENTION creado anteriormente.
Contiene todos los datos fiscales y transaccionales necesarios 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 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 brutos y netos totales.
Detalles de cada línea de venta (bienes o servicios), incluyendo descripción, cantidad, tasa de IVA e importe.
Referencias a recibos anteriores al crear registros de CORRECTION o CANCELLATION.

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

Estados y Modos de Registro

Cada Registro en SIGN IT (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 Registro ha sido recibido, validado y está listo para su procesamiento.
Rejected – El Registro ha sido recibido pero no ha superado nuestras comprobaciones de validación internas. 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 de transmisión externo. Los detalles están disponibles en los mensajes de registro.

Modos

Processing – El Registro está siendo procesado 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 tiene éxito, y procede inmediatamente al siguiente paso.
POST → Rejected	El Registro no supera la validación interna y transiciona automáticamente a `Rejected`, proporcionando registros de errores.
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 del 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.

Resumen

En las operaciones diarias, SIGN IT reemplaza el sencillo flujo de transacciones “Inicio → Fin” de SIGN DE con un modelo de Registro multi-recurso y basado en eventos.
Cada operación — ya sea una venta (RECEIPT), devolución (CORRECTION) o cancelación (CANCELLATION) — se firma, registra y archiva individualmente, garantizando la trazabilidad completa y el cumplimiento de la legislación fiscal italiana.

Was this page helpful?