Planificación de integración

Esta página es para product managers y líderes técnicos que planifican una integración de fiskaly. Cubre estimaciones de esfuerzo, requisitos de equipo, dependencias de productos, hitos de cumplimiento y una plantilla de cronograma de despliegue.

💡Para desarrolladores

Si quiere escribir código, empiece con el Quick Start.

Paso 1: Elegir su arquitectura de API

fiskaly proporciona dos arquitecturas de API. Su elección depende de los países que necesite:

Si necesita…	Use…	Por qué
Solo Alemania, Austria o España	API Especializada para ese país	Creada específicamente, máximo soporte específico por país
Solo Francia o Italia	API Unificada	Arquitectura multi-país — añadir el otro es ~1 semana
Francia + Italia (o + Suecia)	API Unificada	Integra una vez, expándase cambiando el esquema del payload
Alemania + Francia/Italia	Ambas	API Especializada para DE + API Unificada para FR/IT. Mismo patrón de autenticación, diferentes modelos de recursos.
3+ países incluyendo FR/IT	Empiece con API Unificada	Luego añade APIs Especializadas para DE/AT/ES según sea necesario

Consulta La API Unificada para la comparación completa de arquitecturas, el modelo de recursos y el mapeo de terminología.

Paso 2: Determinar el alcance del producto

Los productos de fiskaly que necesita dependen de dónde opera y qué regulaciones se aplican. Use este árbol de decisión:

¿Opera sistemas POS en alguno de estos países?

• Alemania -> SIGN DE + DSFinV-K + SUBMIT DE (los tres son obligatorios)
• Austria -> SIGN AT
• Francia -> SIGN FR (se requiere certificación NF525)
• España -> SIGN ES (TicketBAI o Verifactu, según la región)
• Italia -> SIGN IT
• Suecia -> SIGN SE (InfraSec TCS)
• Bélgica -> E-Invoice (solo B2B, a través de Peppol)

¿Necesita archivo a largo plazo conforme? -> Añade SAFE o SAFE flex

¿Quiere reemplazar los recibos en papel? -> Añade eReceipt (opcional, cualquier país de la UE)

Alemania es el más complejo

Alemania requiere tres productos que trabajen juntos. Así se relacionan:

SIGN DE (firma de transacciones)
  |
  +--> DSFinV-K (generación de exportación fiscal, referencia datos de SIGN DE)
  |
  +--> SUBMIT DE (presentación ELSTER, referencia clientes y TSS de SIGN DE)
  |
  +--> SAFE (archivo opcional de exportaciones)

Para otros países, SIGN es típicamente la única integración obligatoria.

Paso 3: Estimar el esfuerzo de integración

Estos son los cronogramas típicos para un equipo de 1-2 desarrolladores backend con experiencia en el dominio POS. Su cronograma real depende de su arquitectura POS, cadencia de lanzamiento y requisitos de pruebas.

APIs Especializadas (SIGN DE, SIGN AT, SIGN ES)

Producto	Primera integración	Desde SIGN DE	Notas
SIGN DE	4-8 semanas	—	Aprovisionamiento TSS, firma de transacciones, código QR del recibo, manejo de errores
SIGN AT	3-5 semanas	1-2 semanas	El más similar a SIGN DE. SCU en lugar de TSS, registro en FinanzOnline.
SIGN ES	5-7 semanas	2-4 semanas	Gestión de certificados, 6 tipos de factura, envío en tiempo real

API Unificada (SIGN FR, SIGN IT, SIGN SE)

Producto	Primer país de la API Unificada	Cada adicional	Desde SIGN DE	Notas
SIGN FR	4-6 semanas	—	1-3 semanas	La certificación NF525 añade 4-8 semanas por separado
SIGN IT	4-6 semanas	—	1-3 semanas	Lotería de recibos, manejo de pérdida de conexión
FR + IT	4-6 semanas (primero)	~1 semana (segundo)	—	Mismo modelo de recursos — solo difiere el payload y la fiscalización del contribuyente
SIGN SE	2-4 semanas	—	—	Actualmente InfraSec TCS (XML, X.509); API Unificada próximamente

Paso 4: Planificar tu equipo

Rol	Responsabilidad	Cuándo se necesita
Desarrollador backend (1-2)	Integración de API, firma de transacciones, manejo de errores, lógica de reintentos	Todo el período de integración
Desarrollador frontend (0-1)	Renderizado de recibos, visualización de código QR, UI de eReceipt	Después de que el backend de firma funcione
Ingeniero de QA (1)	Pruebas end-to-end, validación de cumplimiento, casos límite (tiempos de espera, sin conexión)	Semanas 5+
Product manager	Decisiones de alcance, recopilación de requisitos de cumplimiento, lista de verificación de entrada en producción	En todo momento
DevOps / Infraestructura (0-1)	Gestión de secrets, monitoreo, alertas por fallos de firma	Preparación para la entrada en producción

Paso 5: Comprender la lista de verificación de cumplimiento

Antes de entrar en producción en cualquier país, verifica estos puntos:

Lista de verificación universal (todos los países)

• Credenciales de API almacenadas en un gestor de secrets (no en el código fuente)
• Caché de tokens implementado (no volver a autenticarse por transacción)
• Lógica de reintentos con retroceso exponencial para errores 5xx y de tiempo de espera
• Tiempo de espera de firma configurado (3-5 segundos) y no bloquea el proceso de pago
• El recibo incluye todos los campos obligatorios para el país de destino
• El manejo de errores cubre la indisponibilidad del TSS (consulta la guía de manejo de errores)
• Las pruebas de integración en el entorno TEST pasan
• El entorno LIVE aprovisionado a través del HUB
• Monitoreo/alertas configurados para fallos de firma y latencia

Lista de verificación específica de Alemania

• TSS creado, PIN de administrador establecido y TSS inicializado
• Cliente creado para cada terminal POS
• El recibo incluye el código QR de KassenSichV (consulta datos del recibo)
• El código QR valida correctamente (consulta validación del código QR)
• La exportación DSFinV-K se genera y valida
• La declaración SUBMIT DE se presenta correctamente con ELSTER
• Cierre de sesión del administrador tras el aprovisionamiento

Paso 6: Preparación para la entrada en producción

1. Completar las pruebas en sandbox

   Ejecuta su conjunto completo de pruebas contra el entorno TEST. Verifica todos los tipos de transacciones, escenarios de error y generación de exportaciones.

2. Solicitar acceso LIVE

   Cambia tu organización al entorno LIVE a través del HUB. Contacte a tu gestor de cuenta si necesita asistencia.

3. Aprovisionar recursos LIVE

   Los recursos de TEST no se transfieren. Vuelva a ejecutar su flujo de aprovisionamiento (creación de TSS, registro de clientes) en el entorno LIVE.

4. Despliegue escalonado

   Empiece con una única ubicación o terminal. Monitoree la latencia de firma, las tasas de error y el cumplimiento de los recibos durante 1-2 semanas antes de expandirse.

5. Configurar monitoreo

   Rastree: tasa de éxito de firma, latencia de firma promedio, tasa de error 401 (problemas de actualización de token) y tasa de error 5xx (problemas del servicio). Alerte cuando la tasa de fallo de firma sea > 1%.

⚠️TEST y LIVE están completamente separados

TSS, clientes, transacciones y exportaciones creadas en TEST no existen en LIVE. Su despliegue de entrada en producción debe incluir un paso de aprovisionamiento.

Enlaces clave para PMs

Descripción general del producto

Qué hace cada producto y cuándo lo necesita

Cobertura de países (E-Invoice)

Cuándo estarán disponibles los nuevos módulos de países

SAFE vs SAFE flex

Qué opción de archivo se adapta a su caso de uso