Buenas Prácticas para Agentes

Esta guía describe el enfoque recomendado para que los agentes de IA integren las APIs de fiskaly — desde el descubrimiento hasta el despliegue en producción. Destaca los errores comunes y los matices por país que dificultan las integraciones automatizadas.

Flujo de integración recomendado

1. Descubrir

   Obt�n /products.json para identificar el producto correcto para su país objetivo. Comprueba apiArchitecture para determinar si está trabajando con una API especializada o unificada.

2. Autenticar

   POST /auth con la clave API y el secreto proporcionados por el usuario. Almacene en caché el token de acceso (TTL de 24h) — no se reautentique por cada solicitud.

3. Aprovisionar

   Crea la infraestructura de firma para el país objetivo: TSS + Client (DE), Taxpayer + Location + System (FR/IT) o equivalente. Comprueba /human-interventions.json para los pasos que requieren intervención humana.

4. Realizar transacciones

   Firme transacciones a través del endpoint apropiado. SIGN DE usa un patrón PUT de dos llamadas (ACTIVE → FINISHED). SIGN FR y SIGN IT usan un patrón POST de dos llamadas (Intention → Transaction).

Acciones automatizables vs. que requieren humano

No todos los pasos de una integración de fiskaly pueden automatizarse. Antes de crear un flujo de trabajo de agente, comprueba qué acciones necesitan un humano:

Categoría	Cantidad	Ejemplos
Completamente automatizable	11	Autenticación, creación de TSS, firma de transacciones
Parcialmente automatizable	2	Introducir datos del contribuyente (el humano proporciona el NIF, el agente realiza la llamada API)
Requiere humano	7	Creación de cuenta, generación de clave API, puesta en producción

Diseñe su agente para que pause e indique al usuario en los pasos que requieren humano, y luego reanude la automatización. Consulta el Registro de Intervenciones Humanas completo para más detalles.

💡Tip

La versión legible por máquinas en /human-interventions.json puede consultarse en tiempo de ejecución para ajustar dinámicamente el flujo de trabajo de su agente.

Antipatrones comunes

Codificar URLs base de forma fija

Las URLs base difieren entre los entornos TEST y LIVE, y entre las APIs especializadas y unificadas. Obténgalas siempre de /products.json en lugar de codificarlas de forma fija.

// No haga esto
const BASE_URL = "https://kassensichv-middleware.fiskaly.com/api/v2";

// Haga esto — lea de products.json
const product = products.find(p => p.id === "sign-de");
const baseUrl = product.baseUrls.test;

Reautenticarse por cada solicitud

El token de acceso es válido durante 24 horas. Almacénelo en caché y solo reautentíquese ante respuestas 401. Reautenticarse por cada solicitud desperdicia tiempo y puede activar límites de tasa.

Saltarse el entorno TEST

Desarrolle y prueba siempre primero contra el entorno TEST (sandbox). TEST es gratuito, usa la misma superficie de API que LIVE y permite iterar sin afectar datos fiscales reales.

Reutilizar UUIDs

Para las APIs especializadas (SIGN DE, SIGN AT, SIGN ES), los IDs de recursos son UUIDs generados por el cliente. Genera siempre UUIDs nuevos — reutilizar un UUID provoca un 409 Conflict.

Ignorar las claves de idempotencia

Para las APIs unificadas (SIGN FR, SIGN IT), las solicitudes POST y PATCH requieren un encabezado X-Idempotency-Key. Genera un UUID nuevo para cada operación única. Los reintentos de la misma operación deben reutilizar la misma clave.

Consultar exportaciones de forma síncrona

Las exportaciones de DSFinV-K y otras operaciones de exportación son asíncronas. Desencadene la exportación y luego sondee la finalización — no bloquee en la solicitud inicial.

Particularidades por país

Alemania (SIGN DE)

⚠️PIN de administrador requerido

La inicialización del TSS requiere establecer un PIN de administrador mediante PATCH /tss/{id} antes de cambiar el estado a INITIALIZED. El PIN debe almacenarse de forma segura — perderlo requiere reemplazar el TSS.

• Máquina de estados del TSS: UNINITIALIZED → INITIALIZED → DISABLED
• UUIDs generados por el cliente para todos los IDs de recursos
• Las transacciones usan un modelo de revisiones: revisión 1 (ACTIVE) → revisión 2 (FINISHED)
• La exportación DSFinV-K es legalmente obligatoria para las auditorías

Francia (SIGN FR)

• Requiere una jerarquía organizacional: Organization GROUP → Organization UNIT → Subject → Taxpayer → Location → System → Record
• La creación de contribuyentes necesita un número SIREN real (proporcionado por un humano)
• Patrón de registro de dos llamadas: Intention (type: INTENTION) → Transaction (type: TRANSACTION)
• Encabezados obligatorios en cada solicitud: X-Api-Version, X-Idempotency-Key, X-Scope-Identifier

Italia (SIGN IT)

• Misma arquitectura de API Unificada que Francia
• El contribuyente necesita credenciales de la Agenzia delle Entrate (AdE) — proporcionadas por un humano
• Compatible con la Lotteria degli Scontrini (lotería de recibos) — incluye lottery_code en los registros cuando el cliente proporciona uno
• El reporte en tiempo real a AdE significa que la firma de transacciones no es segura de reintentar sin claves de idempotencia

Austria (SIGN AT)

• Regulación RKSV con integración de FinanzOnline
• URL base separada: rksv-middleware.fiskaly.com/api/v1
• Exportación DEP (Datenerfassungsprotokoll) para la pista de auditoría

España (SIGN ES)

• Regulaciones TicketBAI y Verifactu
• Firma y envío de facturas en XML (no JSON como otros productos)
• Variaciones regionales entre comunidades autónomas

Scripts de inicio rápido

Hay scripts de inicio rápido de extremo a extremo disponibles para pruebas automatizadas:

• scripts/sign-de-quickstart.mjs — Flujo completo de SIGN DE: autenticación → TSS → cliente → transacción
• scripts/sign-fr-quickstart.mjs — Flujo completo de SIGN FR: autenticación → org → contribuyente → ubicación → sistema → registro

Estos scripts demuestran el flujo completo sin errores y pueden servir como implementaciones de referencia para integraciones construidas por agentes.