La API Unificada

La API Unificada de fiskaly es una arquitectura de integración única que cubre múltiples países. Intégrela una vez para Francia o Italia, y añadir el siguiente país significa cambiar el esquema del payload — no reescribir tu integración.

Esta página documenta cómo funciona la API Unificada, cómo se ve su modelo de recursos y cómo difiere de las APIs Especializadas (SIGN DE, SIGN AT, SIGN ES).

Dos arquitecturas de API

fiskaly proporciona dos arquitecturas de API. Ambas son completamente compatibles y se mantienen activamente:

	API Unificada	APIs Especializadas
Países	Francia (SIGN FR), Italia (SIGN IT), Suecia (próximo)	Alemania (SIGN DE), Austria (SIGN AT), España (SIGN ES)
URLs base	`test.api.fiskaly.com` / `live.api.fiskaly.com`	Específicas del producto (p. ej., `kassensichv.fiskaly.com`)
Gestión de org.	Integrada en la API del producto	Management API separada (`management.fiskaly.com`)
IDs de recursos	Generados por el servidor (use `X-Idempotency-Key`)	UUIDs generados por el cliente
Control de versiones	Encabezado `X-Api-Version` (basado en fecha, sin cambios disruptivos)	Sin encabezado de versión (posibles cambios disruptivos)
Alcance de recursos	Encabezado `X-Scope-Identifier`	Parámetros de ruta
Terminología	Organización, Contribuyente, Ubicación, Sistema, Registro	TSS, cliente, transacción (varía por producto)
Añadir un país	Cambiar esquema del payload dentro del mismo modelo de recursos	Integrar una API separada con diferentes endpoints

📘Ninguna arquitectura es heredada

Las APIs Especializadas están diseñadas específicamente para las regulaciones específicas de su país. SIGN DE es el producto más maduro de fiskaly con más de 10.000 integraciones y certificación BSI válida hasta 2033. La API Unificada es la arquitectura que fiskaly construyó para una expansión eficiente multi-país.

¿Qué arquitectura debería usar?

Escenario	Recomendación
Solo necesita Alemania	SIGN DE (API Especializada)
Solo necesita Austria	SIGN AT (API Especializada)
Solo necesita España	SIGN ES (API Especializada)
Solo necesita Francia o Italia	API Unificada
Necesita Francia + Italia (o + Suecia)	API Unificada — integra una vez, añade países mediante esquema de payload
Necesita Alemania + Francia	Ambas — SIGN DE (Especializada) + SIGN FR (Unificada). Mismo patrón de autenticación, diferentes modelos de recursos.
Está empezando y planifica 3+ países	Empiece con la API Unificada para FR/IT, añade APIs Especializadas para DE/AT/ES según sea necesario

URLs base de la API Unificada

La API Unificada utiliza URLs base separadas para cada entorno:

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

Esto es diferente de las APIs Especializadas (p. ej., SIGN DE), donde se utiliza una única URL base y la API Key determina el entorno.

Encabezados de la API Unificada

Cada solicitud a la API Unificada incluye estos encabezados:

`X-Api-Version`

Obligatorio en cada solicitud. El valor es la fecha de lanzamiento de la versión de la API que está usando (p. ej., 2026-02-03).

X-Api-Version: 2026-02-03

Esto te da control total sobre cuándo adoptar una nueva versión. Puede:

Probar una nueva versión en TEST antes de migrar LIVE
Ejecutar diferentes clientes en diferentes versiones simultáneamente
Garantizar ningún cambio disruptivo dentro de una versión fijada

`X-Idempotency-Key`

Obligatorio en todas las solicitudes POST y PATCH. Dado que los IDs de recursos son generados por el servidor (no por el cliente como en SIGN DE), este encabezado garantiza que las solicitudes reintentadas no crean recursos duplicados.

X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Use un UUIDv4 o UUIDv3 nuevo para cada operación distinta. Use una nueva clave al reintentar una solicitud fallida.

`X-Scope-Identifier`

Se usa para establecer relaciones entre recursos. Reemplaza los parámetros de ruta usados en la Management API y las APIs Especializadas.

X-Scope-Identifier: organization-unit-id

Por ejemplo, al crear una API Key para una Organization::UNIT específica, el encabezado X-Scope-Identifier contiene el ID de la Unidad en lugar de codificarlo en la ruta URL.

Modelo de recursos

La API Unificada usa una jerarquía de recursos estandarizada en todos los países:

Organization::ACCOUNT       ← Tu empresa (nivel superior, gestionada en HUB)
  │
  └── Organization::GROUP   ← Clúster lógico (región, marca, franquicia)
        │
        └── Organization::UNIT   ← Comerciante individual / contribuyente
              │
              ├── Subject::API_KEY   ← Credenciales de API para esta unidad
              │
              ├── Taxpayer (COMPANY o INDIVIDUAL)
              │     │
              │     ├── Información general (nombre, dirección — compartida entre países)
              │     │
              │     └── Información de fiscalización (específica del país: SIREN para FR,
              │         Codice Fiscale para IT, etc.)
              │
              ├── Location   ← Ubicación física del negocio (tienda, local)
              │
              └── System::FISCAL_DEVICE   ← Terminal POS / caja registradora

Estados de recursos

Cada recurso principal (Contribuyente, Ubicación, Sistema) sigue la misma máquina de estados:

ACQUIRED ──→ COMMISSIONED ──→ DECOMMISSIONED
(creado)        (activo)          (retirado)

ACQUIRED — el recurso está creado pero aún no activo. Modo: INACTIVE.
COMMISSIONED — el recurso está activo y listo para producción. Modo: OPERATIVE. Esta transición es irreversible e inicia la facturación.
DECOMMISSIONED — el recurso está permanentemente retirado. Modo: INACTIVE. También irreversible.

Modos operativos dentro del estado COMMISSIONED:

Modo	Significado	Establecido por
`OPERATIVE`	Operación normal	Automático (al comisionar o tras resolver un problema)
`DEGRADED`	Problema detectado	Automático (por el servicio)
`SUSPENDED`	Pausa de mantenimiento	Manual (por ti, a través de la API)

Registros (el modelo de transacción)

En la API Unificada, las transacciones se denominan Registros y usan un modelo de dos pasos:

Record::INTENTION — marca el inicio de una operación fiscal (equivalente a Start-Transaction en SIGN DE)
Record::TRANSACTION — completa la operación fiscal con el payload completo (equivalente a Finish-Transaction en SIGN DE)

Tipos de operación adicionales compatibles solo a través de Record::INTENTION:

EVENT — eventos del sistema (modo de entrenamiento, operaciones de prueba, reinicios)
DUPLICATE — duplicado de un documento fiscal existente
EXPORT — generación de exportación de datos fiscales

📘No todas las operaciones están disponibles en todos los países

Francia soporta intenciones TRANSACTION, EVENT, DUPLICATE y EXPORT. Italia actualmente solo soporta TRANSACTION. Consulta la documentación específica del país para la lista completa.

Próximos pasos

SIGN FR para clientes de SIGN DE

Guía de migración detallada con llamadas a la API paso a paso

SIGN IT para clientes de SIGN DE

Guía de migración detallada con llamadas a la API paso a paso

Planificación de integración

Estimaciones de esfuerzo, cronogramas y listas de verificación de cumplimiento

Was this page helpful?