Mapeo de recursos entre productos

Esta referencia muestra cómo los conceptos clave se mapean entre las arquitecturas de API de fiskaly. Úsela al migrar entre productos o al integrar múltiples países.

Tabla de mapeo de recursos

Concepto	SIGN DE (Especializado)	API Unificada (FR/IT)	Management API
Entidad de nivel superior	Organización (vía HUB)	Organización GROUP	Organización
Unidad de negocio	Organización gestionada	Organización UNIT	Organización gestionada
Dispositivo de firma	TSS (Technical Security System)	System FISCAL_DEVICE	—
Terminal POS	Client	— (implícito a través del Sistema)	—
Transacción	Transaction (PUT con estado)	Record (Intention → Transaction)	—
Entidad fiscal	— (a través de SUBMIT DE)	Taxpayer (COMPANY / INDIVIDUAL)	—
Ubicación	— (a través de DSFinV-K)	Location BRANCH	—
Credenciales	API Key + Secret (HUB)	Subject API_KEY (API)	API Key (HUB)
Endpoint de autenticación	POST /api/v2/auth	POST /api/v1/auth/token	POST /api/v0/auth
IDs de recursos	UUID generado por el cliente	Generado por el servidor	UUID generado por el cliente
Idempotencia	PUT con UUID en URL	Encabezado X-Idempotency-Key	PUT con UUID en URL

Estados del ciclo de vida

Los recursos en cada arquitectura siguen diferentes máquinas de estados:

SIGN DE — Estados del TSS

UNINITIALIZED → INITIALIZED → DISABLED

• Debe establecer el PIN de administrador y autenticarse antes de la inicialización
• No puede habilitarse de nuevo una vez deshabilitado

API Unificada — Estados de los recursos

ACQUIRED → COMMISSIONED → DECOMMISSIONED

Se aplica a: Contribuyente, Ubicación, Sistema

• Los recursos se crean en estado ACQUIRED
• Deben actualizarse a COMMISSIONED antes del uso operativo
• DECOMMISSIONED es terminal

SIGN DE — Estados de la transacción

ACTIVE (revisión 1) → FINISHED (revisión 2)

API Unificada — Flujo de registro

INTENTION → TRANSACTION

• Se requieren dos llamadas a la API separadas
• La transacción hace referencia a la intención por ID

Comparación de secuencias de configuración

SIGN DE (Alemania)

1. Crear organización (HUB)
2. Generar API Key (HUB)
3. Autenticar (POST /auth)
4. Crear TSS (PUT /tss/{id})
5. Inicializar TSS (PIN de administrador → Autenticación → Cambio de estado)
6. Crear Client (PUT /tss/{id}/client/{id})
7. Crear Transaction (PUT /tss/{id}/tx/{id})

API Unificada (Francia/Italia)

1. Registrarse en HUB
2. Crear organización GROUP (HUB)
3. Generar API Key (HUB)
4. Crear Token (POST /auth/token)
5. Crear organización UNIT
6. Crear Subject API_KEY
7. Crear Token (para UNIT)
8. Crear Taxpayer → Comisionar
9. Crear Location → Comisionar
10. Crear System → Comisionar
11. Crear Record (Intention → Transaction)

📘Más pasos, más estructura

La API Unificada tiene más pasos de configuración porque incluye gestión de organizaciones (jerarquía GROUP/UNIT), datos de contribuyentes y seguimiento de ubicaciones directamente en la API del producto — características que SIGN DE maneja a través de productos separados (Management API, SUBMIT DE, DSFinV-K).

Diferencias clave

Aspecto	APIs Especializadas	API Unificada
URLs base	Por producto (p. ej., kassensichv.fiskaly.com)	Compartida (test.api.fiskaly.com)
Gestión de org.	A través de la Management API + HUB	Integrada en la API del producto
Creación de recursos	PUT con UUID generado por el cliente	POST con ID generado por el servidor
Versionado	Ruta URL (/api/v2)	Encabezado (X-Api-Version: 2026-02-03)
Alcance	Implícito (a través del token de autenticación)	Explícito (encabezado X-Scope-Identifier)
Modelo de transacción	Recurso único con cambios de estado	Dos pasos: Intención y luego Transacción

Recursos relacionados

Descripción general de la API Unificada

Comparación completa de las dos arquitecturas de API

Configuración de SIGN DE

Guía paso a paso para la fiscalización alemana

Configuración de SIGN FR

Guía paso a paso para la fiscalización francesa