Conceptos fundamentales

Antes de integrar cualquier producto de fiskaly, es útil comprender los bloques de construcción de la plataforma. Estos conceptos se aplican a todos los países y productos.

Organizaciones

fiskaly utiliza un modelo de organización jerárquico para representar tu estructura empresarial:

🏢

Account

Su entidad de nivel superior. Creada cuando se registra en el HUB. Representa al proveedor POS o comerciante.

📂

Group

Un nivel intermedio que te permite agrupar múltiples unidades. Útil para organizar por región o marca.

🏪

Unit

Representa a un único comerciante o entidad legal. Cada unidad tiene tus propios datos de contribuyente y recursos fiscales.

En las APIs más nuevas (SIGN PT, SIGN IT, SIGN FR, E-Invoice), estos se denominan tipos de organización GROUP y UNIT. En SIGN DE, las organizaciones gestionadas cumplen el mismo propósito.

Entornos

Cada cuenta de fiskaly tiene dos entornos aislados:

Entorno	Propósito	Datos
TEST	Desarrollo y pruebas de integración	Simulados — sin conexión a las autoridades fiscales
LIVE	Operaciones de producción	Reales — las transacciones se notifican a las autoridades fiscales

⚠️LIVE es permanente

Los registros creados en el entorno LIVE son legalmente vinculantes y se transmiten a las autoridades fiscales. Desarrolle y prueba siempre primero en el entorno TEST.

Las API Keys generadas en TEST crean recursos TEST; las generadas en LIVE crean recursos LIVE. Los dos entornos están completamente separados — no hay intercambio de datos entre ellos.

Autenticación

Todas las APIs de fiskaly utilizan autenticación basada en JWT:

POST /auth  (or POST /tokens)
  { "api_key": "...", "api_secret": "..." }
    → { "access_token": "...", "refresh_token": "..." }

Token	Validez	Uso
access_token	24 horas	Incluir como Authorization: Bearer <token> en todas las solicitudes de API
refresh_token	48 horas	Usar para obtener un nuevo token de acceso sin volver a autenticarse

💡Almacene tus tokens en caché

No vuelvas a autenticarte en cada solicitud. Almacene el token de acceso en caché y solo renuévelo cuando reciba una respuesta 401. Volver a autenticarse en cada llamada añade latencia innecesaria a tu proceso de pago.

Autenticación con alcance (SIGN PT, SIGN IT, SIGN FR, E-Invoice)

Las APIs más nuevas utilizan encabezados adicionales para limitar las solicitudes a una organización específica:

Encabezado	Propósito
Authorization: Bearer <token>	Autenticación
X-Api-Version: 2026-02-03	Selección de versión de API
X-Scope-Identifier: <org_id>	Limitar solicitudes a una unidad organizativa específica
X-Idempotency-Key: <uuid>	Garantizar que las operaciones de escritura sean idempotentes

Modelo de recursos

Aunque los recursos exactos varían por país, la mayoría de los productos de fiskaly siguen un patrón común:

Account / Group
  └── Unit (Organización)
        └── Taxpayer (Contribuyente)
              └── Location (Branch / Head Office)
                    └── System (Dispositivo fiscal / POS)
                          └── Record / Transaction (Registro / Transacción)

Ciclo de vida del recurso

La mayoría de los recursos siguen una máquina de estados:

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

• ACQUIRED: El recurso se crea pero aún no está activo
• COMMISSIONED: El recurso está activo y puede procesar transacciones
• DECOMMISSIONED: El recurso está retirado y ya no acepta nuevas operaciones

En SIGN DE, los estados equivalentes son CREATED → INITIALIZED → DISABLED.

Recursos específicos por país

Concepto	Alemania (SIGN DE)	Austria (SIGN AT)	España (SIGN ES)	Italia (SIGN IT)	Portugal (SIGN PT)	Francia (SIGN FR)
Unidad de firma	TSS	SCU	Signer	System	System	System
Terminal POS	Client	Caja registradora	Client	System	System	System
Registro fiscal	Transaction	Receipt	Invoice	Record	Record	Record
Autoridad fiscal	BSI / BZSt	FinanzOnline	AEAT / DFAs vascas	AdE (Agenzia delle Entrate)	AT (Autoridade Tributária e Aduaneira)	DGFiP

URLs base

Cada producto tiene su propio endpoint de API. Consulta la referencia URLs base y entornos para una lista completa.

Producto	Entorno de prueba	Entorno de producción
SIGN DE	kassensichv-middleware.fiskaly.com/api/v2	kassensichv.fiskaly.com/api/v2
SIGN AT	rksv.fiskaly.com/api/v1	rksv.fiskaly.com/api/v1
SIGN ES	test.es.sign.fiskaly.com/api/v1	live.es.sign.fiskaly.com/api/v1
SIGN IT	test.api.fiskaly.com	live.api.fiskaly.com
SIGN FR	test.api.fiskaly.com	live.api.fiskaly.com

¿Qué sigue?

Quick Start

Realiza tu primera llamada a la API en menos de 5 minutos

Referencia de autenticación

Guía de autenticación detallada con flujos de actualización de token

Códigos de error

Comprender y solucionar errores de API