Para clientes de SIGN DE

⚠️Warning

Está viendo la documentación de la versión de API 2026-05-04. La versión más reciente es 2026-06-01.

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

Esta guía explica las principales diferencias con SIGN DE y le ayuda a integrar con éxito la API fiskaly SIGN IT. Describe todos los pasos necesarios para usted 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), así como otros países futuros, con un esfuerzo adicional mínimo.

A diferencia de SIGN DE, SIGN IT no requiere una API de gestión separada. Todos los endpoints necesarios para la autenticación, la creación de organizaciones, la configuración y la gestión de registros fiscales están incluidos directamente en 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 es diferente de SIGN DE, donde solo existe 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 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 simples y confiables.

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 le otorga 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 migrar a la nueva versión solo una vez que todo haya sido verificado. Esto también le permite mantener algunos clientes en una versión anterior si es necesario, mientras incorpora nuevos clientes directamente con la última versión.

Principal ventaja: sin más cambios incompatibles en su versión en ejecución.

X-Idempotency-Key

Dado que los IDs de recursos ya no necesitan ser definidos por usted sino que son generados por la API, el X-Idempotency-Key garantiza que una llamada a la API sea procesada 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 API de gestión 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é Organization::UNIT pertenece una clave API).

Correspondencia 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 un comerciante o contribuyente individual. Cada `Organization::UNIT` está vinculada a un `Taxpayer`.
`Taxpayer::COMPANY` o `Taxpayer::INDIVIDUAL`	En Alemania, forma parte de la `managed_organization` (DSFINVK DE) o `taxpayer` (SUBMIT DE)	Define el contribuyente para la `Organization::UNIT` vinculada, necesario para cumplir las obligaciones fiscales.
`Location`	Comparable: `establishment` (SUBMIT DE)	Representa la(s) ubicación(es) física(s) (p. ej. tiendas) operada(s) por el contribuyente.
`System::FISCAL_DEVICE`	`client`	Representa el sistema POS / la caja registradora utilizada para la fiscalización.
`Subject::API_KEY`	`API key`	Objeto de autenticación mediante clave API, 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, o de otro evento individual procesado en la caja registradora.
`Record::TRANSACTION`	`Finish-Transaction`	Marca la finalización (cierre) 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 SIGN IT. A diferencia de SIGN DE, ya no necesita utilizar la Management API para crear o gestionar estructuras organizativas. Todas las funcionalidades necesarias son parte de SIGN IT en sí mismo.

POST: Create Token

Utilice este token para autenticar la creación de la estructura organizativa para Italia.
Funciona del mismo modo que el token en SIGN DE (API de gestión), que se creaba con la clave API de la organización (principal) y luego se usaba para crear managed_organizations.
En SIGN IT, este token es ahora necesario para crear recursos Organization::UNIT.

POST: Create Organization (UNIT)

Cree una Organization::UNIT (Organización de tipo Unit) que representa a su primer cliente. Esto equivale 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 física. Definirá estos detalles en el paso Taxpayer (COMPANY / INDIVIDUAL) a continuación.

POST: Create Subject (API Key)

Cada uno de sus clientes necesita su propia clave API para crear recursos dentro del ámbito de su Organization::UNIT específica.
Por esta razón, se debe crear un Subject::API_KEY (Subject de tipo clave API).

Vincule 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: Create Token (scoped)

Este token está limitado al ámbito de la Organization::UNIT. Utilícelo para todas las operaciones específicas del contribuyente.

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

POST: Create Taxpayer (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.

Dado que 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 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 del contribuyente 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 normativas nacionales.

PATCH: Update Taxpayer

Actualice el estado de ACQUIRED a COMMISSIONED para activar el Taxpayer.

A diferencia de SIGN DE, los Taxpayers en SIGN IT tienen un atributo state.
Cuando se crea un Taxpayer, su estado inicial es ACQUIRED.
Antes de que pueda utilizarse, el Taxpayer 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 Taxpayer 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 Taxpayer.

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

Cuando el Taxpayer está en el estado ACQUIRED o DECOMMISSIONED, su modo es siempre INACTIVE.
En este modo, el recurso no puede utilizarse.
Cuando el Taxpayer se actualiza al estado COMMISSIONED, el servicio SIGN IT valida automáticamente todas las configuraciones necesarias.
Si tiene éxito, el modo cambia a OPERATIVE.
Si hay un problema con el Taxpayer 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 devuelve el modo a OPERATIVE.
El modo SUSPENDED puede configurarse manualmente para Taxpayers en el estado COMMISSIONED mediante el endpoint updateTaxpayer.
Esto es útil para pausar temporalmente las operaciones fiscales, por ejemplo, al actualizar credenciales o realizar tareas de mantenimiento.

Resumen:

INACTIVE: Modo predeterminado para ACQUIRED y DECOMMISSIONED
OPERATIVE: Modo de producción normal
DEGRADED (aún no implementado): Configurado automáticamente por el servicio SIGN IT debido a un problema
SUSPENDED: Modo de mantenimiento manual

POST: Create 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 Location separada.
En la solución SIGN IT, 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: Update Location

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

POST: Create System

Un System de tipo FISCAL_DEVICE representa un sistema POS o una 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, se debe proporcionar información adicional sobre el sistema de registro electrónico en sí.
La mayoría de estos detalles son normalmente definidos por el proveedor del POS.
En Alemania, esta información suele añadirse posteriormente como parte del proceso 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: Update System

Actualice 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 configurado como 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 configurarse como DECOMMISSIONED, lo cual — como en SIGN IT en general — es irreversible.

El atributo mode refleja el estado operativo del sistema (por ejemplo, OPERATIVE, SUSPENDED, o DEGRADED). DEGRADED aún no está implementado.

Configuración completada

Con el System puesto en servicio correctamente, la fase de configuración inicial está completa.
Todas las estructuras organizativas y fiscales — desde la Organization::UNIT hasta el Taxpayer y el 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 la caja registradora.
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 como se requiere en Italia.

Operaciones diarias en la caja registradora

Una vez completada la configuración y puestos en servicio todos los recursos, el proceso de fiscalización en SIGN IT continúa con las operaciones diarias.
Estas operaciones representan las actividades comerciales diarias en la caja registradora — 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 IT introduce un modelo de Record unificado y con más datos.
Cada transacción se representa como uno o más Records, que son firmados digitalmente, registrados en un diario y archivados para garantizar el cumplimiento fiscal completo.

POST: Create Record

En SIGN IT, 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) por dos recursos independientes: un Record de tipo INTENTION y un 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 posteriormente se actualiza a un estado finalizado.
En SIGN IT, 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.
En Italia, la operación de intención admitida es 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 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 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 estrechamente alineados con la información contenida en una transacción dentro de un cierre de caja (Kassenabschluss) en DSFinV-K DE.

Estados y modos de los Records

Transición	Descripción
POST → Accepted	El Record se crea y entra temporalmente en el estado `Accepted` si la validación tiene éxito.
POST → Rejected	El Record no supera la validación interna y pasa automáticamente a `Rejected`, proporcionando registros de error.
Accepted → Completed	Configurado automáticamente cuando el procesamiento finaliza con éxito.
Accepted → Failed	Configurado cuando el procesamiento falla debido a un componente externo.
Processing → Finished	Indica que el procesamiento ha finalizado, independientemente del éxito o el fracaso.

Resumen

En las operaciones diarias, SIGN IT reemplaza el flujo de transacciones simple «Iniciar → Finalizar» de SIGN DE por un modelo de Record multi-recurso y orientado a eventos.
Cada operación — ya sea una venta (RECEIPT), una devolución (CORRECTION) o una cancelación (CANCELLATION) — se firma, registra en el diario y archiva individualmente, garantizando la trazabilidad completa y el cumplimiento de la legislación fiscal italiana.

Was this page helpful?