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.
Si quiere escribir código, empiece con el Quick Start.
Paso 1: Elegir su arquitectura de API
Sección titulada «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, Italia o Portugal | Unified API | Arquitectura multi-país — añadir otro es ~1 semana |
| Francia + Italia (o + Portugal o + Suecia) | Unified API | Integra una vez, expándase cambiando el esquema del payload |
| Alemania + Francia/Italia/Portugal | Ambas | API Especializada para DE + Unified API para FR/IT/PT. Mismo patrón de autenticación, diferentes modelos de recursos. |
| 3+ países incluyendo FR/IT/PT | Empiece con Unified API | Luego añade APIs Especializadas para DE/AT/ES según sea necesario |
Consulta La Unified API para la comparación completa de arquitecturas, el modelo de recursos y el mapeo de terminología.
Paso 2: Determinar el alcance del producto
Sección titulada «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
- Portugal -> SIGN PT
- 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
Sección titulada «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
Sección titulada «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)
Sección titulada «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 |
Unified API (SIGN FR, SIGN IT, SIGN PT, SIGN SE)
Sección titulada «Unified API (SIGN FR, SIGN IT, SIGN PT, SIGN SE)»| Producto | Primer país de la Unified API | 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 |
| SIGN PT | 4-6 semanas | — | — | Credenciales del portal AT requeridas por adelantado; exportación SAF-T (PT) |
| 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); Unified API próximamente |
Paso 4: Planificar tu equipo
Sección titulada «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
Sección titulada «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)
Sección titulada «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
Sección titulada «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
Sección titulada «Paso 6: Preparación para la entrada en producción»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.
Solicitar acceso LIVE
Cambia tu organización al entorno LIVE a través del HUB. Contacte a tu gestor de cuenta si necesita asistencia.
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.
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.
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%.
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.