Para clientes de SIGN DE

⚠️ Está viendo la documentación de la versión de API 2026-02-03. La versión más reciente es 2026-05-04. La nueva versión de la API no trae cambios en la integración italiana. Sin embargo, añade soporte para SIGN PT, lo que permite a los equipos que planean expandirse a Portugal reutilizar la misma integración ya existente para Italia.

Guía de integración de SIGN IT 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 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 usar SIGN FR (Francia), así como otros países próximos, con un esfuerzo adicional mínimo.

A diferencia de SIGN DE, SIGN IT 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 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 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 solo hay 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 permanezca igual.

En SIGN IT, 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 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 las integraciones más simples 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 usar 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 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 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 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 scope (por ejemplo, a qué Organization::UNIT pertenece una Clave API).

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

SIGN IT	SIGN DE	Explicación
`Organization::ACCOUNT`	(sin equivalente)	Estructura de nivel superior en fiskaly HUB. Representa la cuenta completa 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 del `taxpayer` (SUBMIT DE)	Define el contribuyente para la `Organization::UNIT` vinculada, necesario para cumplir con 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 TPV / 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: una `Record::INTENTION` y una `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Marca el inicio de un proceso de compra, u otro evento individual que se procesa en la caja registradora.
`Record::TRANSACTION`	`Finish-Transaction`	Marca la finalización 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 Clave API 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 usar la Management para crear o gestionar estructuras organizativas. Toda la funcionalidad requerida forma 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 creó utilizando la Clave API de la organización (principal) y luego se usó para crear managed_organizations.
En SIGN IT, este token ahora es 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 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 natural. Definirá estos detalles en el paso Taxpayer (COMPANY / INDIVIDUAL) a continuación.

POST: Crear Subject (Clave API)

Cada uno de tus clientes necesita su propia Clave API para crear recursos dentro del scope específico de su Organization::UNIT.
Por esta razón, se debe crear un Subject::API_KEY (Subject de tipo Clave API).

Vincula su 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 a través del 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 scope)

Este token está limitado al scope de la Organization::UNIT. Úselo para todas las operaciones específicas del contribuyente.

Con la Clave API creada previamente para la Organization::UNIT, debe crear este token con scope.
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 ya sea una persona jurídica (empresa) o una persona física (autónomo).
Cada contribuyente debe crearse antes de que se puedan realizar operaciones fiscales.

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

Información general (compartida entre todos los países):
Incluye atributos comunes como el nombre y 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 Italia, esto incluye atributos fiscales como el número fiscal (Codice Fiscale) y el número de IVA (Partita IVA) 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 IT tienen un atributo state (estado).
Cuando se crea un Contribuyente, su estado inicial es ACQUIRED.
Antes de que pueda usarse, 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 una vez que sea seguro que el cliente ya no utilizará este Contribuyente.

Además de los estados, cada Contribuyente en SIGN IT tiene un atributo mode (modo) que define su estado operativo.

Cuando el Contribuyente está en estado ACQUIRED o DECOMMISSIONED, su modo es siempre INACTIVE.
En este modo, el recurso no puede utilizarse.
Cuando el Contribuyente 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 el Contribuyente 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 restaurará el modo a OPERATIVE.
El modo SUSPENDED puede configurarse manualmente para Contribuyentes en estado COMMISSIONED usando el endpoint updateTaxpayer.
Esto es útil para pausar temporalmente las operaciones fiscales, por ejemplo, cuando se actualizan credenciales o se realiza mantenimiento. Si el servicio SIGN IT establece el Contribuyente en modo DEGRADED (aún no implementado) 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 vuelta 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 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 IT, esto no requiere una Organization::UNIT separada.
Todas las ubicaciones de un contribuyente están representadas 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 poder usarse.
Solo después de este paso la ubicación se vuelve activa y puede utilizarse.

POST: Crear Sistema

Un System de tipo FISCAL_DEVICE representa un TPV o caja registradora.
Corresponde al client 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 propio sistema de registro electrónico.
La mayoría de estos detalles son definidos típicamente por el proveedor de TPV.
En Alemania, esta información generalmente se agrega más tarde como parte del proceso DSFinV-K DE o Submit DE — en SIGN IT, 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 estado y modo que un Taxpayer.
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 Taxpayer, 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 comisionado correctamente, la fase de configuración inicial está completa.
Todas las estructuras organizativas y fiscales — desde Organization::UNIT hasta Taxpayer 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 TPV.
Esto incluye crear y procesar registros fiscales que representan ventas, devoluciones y otros eventos — equivalentes a las transacciones en SIGN DE, pero con datos fiscales extendidos según lo requerido en Italia.

Operaciones diarias en el TPV

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

Si bien el concepto general es similar a SIGN DE, SIGN IT 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 diario y se archivan para garantizar el cumplimiento fiscal completo.

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 transacción en dos pasos de SIGN DE (ACTIVE → FINISHED) con dos recursos independientes: un Registro de tipo INTENTION y otro Registro 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 es reemplazada 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 soportada es TRANSACTION.

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 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 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 previamente.
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 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 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 de CORRECTION o CANCELLATION.

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

Estados y modos de Registro

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

Estados

Accepted (Aceptado) – El Registro ha sido recibido, validado y está listo para su procesamiento.
Rejected (Rechazado) – El Registro ha sido recibido pero no ha superado nuestras verificaciones de validación internas. Los detalles están disponibles en los mensajes de registro.
Completad (Completado) – El Registro ha sido procesado correctamente.
Failed (Fallido) – El Registro no pudo procesarse debido a un error de transmisión externo. Los detalles están disponibles en los mensajes de registro.

Modos

Processing (Procesando) – El Registro está siendo procesado actualmente.
Finished (Finalizado) – El Registro ha sido procesado, exitosamente o no.

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 la validación interna y transiciona 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 ha sido completado, independientemente del éxito o fracaso.

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

Resumen

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

Was this page helpful?