Para Clientes de SIGN DE

⚠️ Está viendo la documentación de la versión de API 2024-10-31. 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 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 estará preparado para usar SIGN FR (Francia) y SIGN ES (España), 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 autenticación, creación de activos, configuración y gestión de registros fiscales están incluidos directamente en SIGN IT — haciendo la integración más rápida y sencilla.

Entornos: TEST y LIVE

En SIGN IT, 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 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 sea la misma.

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 cabeceras HTTP nuevas 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 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 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 haya sido verificado. Esto también te permite mantener algunos clientes en una versión más antigua si es necesario, mientras incorpora nuevos clientes directamente con la más reciente.

Ventaja principal: sin más cambios disruptivos en su versión activa.

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 requerido 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 alcance (por ejemplo, a qué Asset::UNIT pertenece una API Key).

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

SIGN IT	SIGN DE	Explicación
`Asset::TENANT`	(sin equivalente)	Estructura de nivel superior en el fiskaly HUB. Representa la cuenta completa del cliente. No puede anidarse dentro de otros activos.
`Asset::GROUP` (opcional)	`organisation` (con `billing_options`)	Capa intermedia opcional utilizada para organizar múltiples contribuyentes en clústeres 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 `managed_organization` (DSFINVK DE) o `taxpayer` (SUBMIT DE)	Define al contribuyente para el `Asset::UNIT` vinculado, necesario para cumplir las obligaciones fiscales.
`Entity::LOCATION`	Comparable: `establishment` (SUBMIT DE)	Representa ubicación(es) física(s) (p. ej. tiendas) operadas por el contribuyente.
`System::FISCAL_DEVICE`	`client`	Representa el POS / sistema de caja 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 el sistema de caja. Siempre requiere dos llamadas: un `Record::INTENTION` y un `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Marca el inicio de un proceso de compra, o un único evento que se procesa en el sistema de caja.
`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 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 SIGN IT. A diferencia de SIGN DE, ya no necesita usar Management para crear o gestionar estructuras organizativas. Toda la funcionalidad requerida forma parte de SIGN IT en sí.

POST: Crear Token

Use 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ó usando la API Key de la organización (principal) y luego se usó 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 Management 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 alcance específico de Asset::UNIT.
Por esta razón, se debe crear un Subject::API_KEY (Subject de tipo Clave API).

Vincula su Clave API al Asset::UNIT usando 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 del Asset::UNIT al que pertenece la Clave API.

POST: Crear Token (con alcance)

Este token tiene alcance al 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 alcance.
Se usará 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 legal (empresa) o una persona física (autónomo).
Cada contribuyente debe crearse como una Entity antes de que se puedan realizar operaciones fiscales.

Como SIGN IT sigue el enfoque de API Unificada, la estructura de Entity está diseñada de manera estandarizada y dividida 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 las regulaciones nacionales, como el número de identificación fiscal 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) 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 IT tienen un atributo state.
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 punto, el recurso es 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 IT tiene un atributo mode que define su estado operativo.

Cuando la Entity está en estado ACQUIRED o DECOMMISSIONED, su modo siempre es INACTIVE.
En este modo, el recurso no puede usarse.
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 configurarse manualmente para Entities en estado COMMISSIONED usando 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 acción del usuario, el modo primero debe cambiarse a SUSPENDED mientras se realizan las acciones necesarias, y luego actualizarse 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 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 (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 que pueda usarse.
Solo después de este paso la ubicación se activa y puede usarse.

POST: Crear System

Un System de tipo FISCAL_DEVICE representa un POS o sistema de caja.
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 de POS.
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 ú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 cual — 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, 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 POS.
Esto incluye crear y procesar 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 Italia.

Operaciones Diarias en el POS

Una vez completada la configuración y comisionados 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 el POS — como emitir recibos, procesar devoluciones o gestionar 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 están firmados digitalmente, registrados en diario y archivados para garantizar la plena conformidad fiscal.

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

POST: Crear 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) con dos recursos independientes: un Record 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 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 soportada 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 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 transaccionales requeridos para la operación.
Comparado 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 y montos brutos y netos totales.
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 de CORRECTION o CANCELLATION.

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

Estados y Modos de los Registros

Cada Record en SIGN IT (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 Record ha sido recibido, validado y está listo para su procesamiento.
Rejected – El Record ha sido recibido pero no ha superado nuestras verificaciones de validación internas. Los detalles están disponibles en los mensajes de registro.
Completad – El Record ha sido procesado correctamente.
Failed – El Record no pudo procesarse debido a un fallo de transmisión externo. Los detalles están disponibles en los mensajes de registro.

Modos

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

Transiciones

Transición	Descripción
POST → Accepted	El Record se crea y entra temporalmente en el estado `Accepted` si la validación tiene éxito, procediendo inmediatamente al siguiente paso.
POST → Rejected	El Record 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 se ha completado, independientemente del éxito o fracaso.

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

Resumen

En las operaciones diarias, SIGN IT reemplaza el simple flujo de transacción “Inicio → Finalización” de SIGN DE con un modelo de Record 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 la conformidad con la ley fiscal italiana.

Was this page helpful?