Integración de IA y Agentes

fiskaly ofrece un conjunto completo de endpoints legibles por máquinas y herramientas diseñadas para agentes de IA, asistentes de programación y pipelines de integración automatizados. Esta sección documenta cómo descubrir, consultar e integrar las APIs de fiskaly de forma programática, sin necesidad de leer documentación HTML.

Arquitectura

Los agentes de IA interactúan con fiskaly a través de un sistema de descubrimiento por capas:

┌─────────────────────────────────────────────────┐
│  Discovery Layer                                │
│  llms.txt → CLAUDE.md → ai-plugin.json          │
├─────────────────────────────────────────────────┤
│  Structured Data                                │
│  products.json → regulatory.json                │
│  human-interventions.json                       │
├─────────────────────────────────────────────────┤
│  API Specifications                             │
│  9 OpenAPI specs (JSON/YAML)                    │
├─────────────────────────────────────────────────┤
│  Interactive Tooling                            │
│  MCP Server (search, specs, products, errors)   │
└─────────────────────────────────────────────────┘

1. Descubrimiento — llms.txt y ai-plugin.json informan a los agentes sobre qué es fiskaly y dónde encontrar datos estructurados.
2. Datos estructurados — products.json proporciona metadatos de productos legibles por máquinas con URLs base, URLs de especificaciones y enlaces a la documentación.
3. Especificaciones de API — 9 especificaciones OpenAPI cubren todos los endpoints de todos los productos de fiskaly.
4. Herramientas interactivas — El servidor MCP permite a los agentes buscar documentación, recuperar especificaciones y consultar códigos de error en tiempo real.

Primeros pasos como agente de IA

1. Obtener el índice de descubrimiento

   Comienza con https://workspace.fiskaly.com/llms.txt para un índice en texto plano de toda la documentación y las especificaciones, o con /CLAUDE.md para una guía de integración estructurada.

2. Identificar el producto correcto

   Consulta https://workspace.fiskaly.com/products.json para encontrar el producto que corresponde a su país objetivo. Cada entrada incluye apiArchitecture, baseUrls y specUrl.

3. Cargar la especificación OpenAPI

   Obtén la URL de la especificación del manifiesto del producto (p. ej., /specs/sign-de-v2.json) para obtener definiciones completas de endpoints, esquemas de solicitud/respuesta y detalles de autenticación.

4. Verificar los pasos que requieren intervención humana

   Consulta /human-interventions.json para identificar qué pasos necesitan un humano (creación de cuenta, claves API, puesta en producción) y cuáles son completamente automatizables.

💡¿Usando Claude Code o Cursor?

Conecta el servidor MCP de fiskaly para acceso interactivo a documentación, especificaciones y códigos de error — sin necesidad de realizar peticiones HTTP. Consulta la guía del servidor MCP.

Contenido de esta sección

Servidor MCP

Configura y use el servidor MCP fiskaly-docs en Claude Code, Cursor o cualquier cliente MCP.

Endpoints Legibles por Máquinas

Todos los endpoints de descubrimiento y datos con URLs, formatos y ejemplos de uso.

Buenas Prácticas para Agentes

Flujo de integración recomendado, antipatrones comunes y peculiaridades por país.

Intervenciones Humanas

Qué acciones son automatizables y cuáles requieren intervención humana.