Endpoints Legibles por Máquinas

fiskaly publica un conjunto de endpoints legibles por máquinas junto al sitio de documentación legible por humanos. Estos endpoints están diseñados para agentes de IA, rastreadores LLM y pipelines de automatización que necesitan acceso estructurado a metadatos de productos, especificaciones de API y datos regulatorios.

Referencia de endpoints

Endpoint	Formato	Propósito
/llms.txt	Texto plano	Índice de descubrimiento LLM — lista todas las páginas de documentación y URLs de especificaciones
/llms-full.txt	Texto plano	Volcado completo de documentación para ingesta de contexto LLM
/products.json	JSON	Manifiesto de productos con metadatos, URLs base y URLs de especificaciones para los 14 productos
/human-interventions.json	JSON	Registro de acciones automatizables vs. que requieren humano con recuentos resumidos
/regulatory.json	JSON	Requisitos regulatorios y detalles de cumplimiento por país
/.well-known/ai-plugin.json	JSON	Manifiesto del plugin de IA (formato de especificación de plugin OpenAI)
/CLAUDE.md	Markdown	Guía de integración para agentes con autenticación, patrones y referencia por país
/specs/sign-de-v2.json	JSON	Especificación OpenAPI de SIGN DE v2
/specs/spec-sign-at.json	JSON	Especificación OpenAPI de SIGN AT (RKSV)
/specs/fiskaly.sign-fr.2026-02-03.yaml	YAML	Especificación OpenAPI de SIGN FR (API Unificada)
/specs/fiskaly.sign-it.2026-02-03.yaml	YAML	Especificación OpenAPI de SIGN IT (API Unificada)
/specs/fiskaly.e-invoice-be.2026-02-03.yaml	YAML	Especificación OpenAPI de E-INVOICE BE (API Unificada)
/specs/fiskaly.e-invoice-de.2026-02-03.yaml	YAML	Especificación OpenAPI de E-INVOICE DE (API Unificada)
/specs/spec-sign-es.yaml	YAML	Especificación OpenAPI de SIGN ES
/specs/spec-dsfinvk.json	JSON	Especificación OpenAPI de DSFinV-K
/specs/spec-ereceipt.json	JSON	Especificación OpenAPI de eReceipt
/specs/spec-merchant.json	JSON	Especificación OpenAPI de la Management API
/specs/spec-obono.json	JSON	Especificación OpenAPI de obono (SIGN AT SaaS)

Todos los endpoints se sirven desde https://workspace.fiskaly.com.

Flujo de descubrimiento

Un flujo de descubrimiento típico de un agente tiene el siguiente aspecto:

1. Obtener /llms.txt
   → Obtener un índice de toda la documentación y especificaciones disponibles

2. Obtener /products.json
   → Encontrar el producto que corresponde al país objetivo
   → Extraer baseUrls, specUrl y docsUrl

3. Obtener /specs/{product-spec}
   → Cargar la especificación OpenAPI completa para el producto elegido

4. Obtener /human-interventions.json
   → Identificar qué pasos son automatizables vs. que requieren humano

products.json

El manifiesto de productos es el endpoint principal de datos estructurados. Cada entrada de producto incluye:

{
  "id": "sign-de",
  "name": "SIGN DE",
  "description": "German fiscal signing (KassenSichV)",
  "country": "DE",
  "apiArchitecture": "specialized",
  "baseUrls": {
    "test": "https://kassensichv-middleware.fiskaly.com/api/v2",
    "live": "https://kassensichv.fiskaly.com/api/v2"
  },
  "specUrl": "/specs/sign-de-v2.json",
  "docsUrl": "/countries/germany",
  "apiReferenceUrl": "/api/sign-de"
}

Use apiArchitecture para determinar el patrón de integración:

• specialized — URL base por país, UUIDs generados por el cliente, Management API separada
• unified — URLs base compartidas, IDs generados por el servidor, encabezados obligatorios (X-Api-Version, X-Idempotency-Key, X-Scope-Identifier)
• platform — servicios entre productos (DSFinV-K, eReceipt, Management API)

human-interventions.json

Devuelve todas las acciones de integración categorizadas por nivel de automatización:

{
  "summary": {
    "fullyAutomatable": 11,
    "partiallyAutomatable": 2,
    "requiresHuman": 7
  },
  "interventions": [
    {
      "action": "Authenticate (get token)",
      "product": "All",
      "automatable": "yes",
      "reason": "Standard API call",
      "whatToDo": "POST /auth with api_key + api_secret"
    }
  ]
}

Consulta el Registro de Intervenciones Humanas para obtener la referencia legible por humanos completa.

ai-plugin.json

El manifiesto del plugin de IA sigue el formato de especificación del plugin OpenAI:

{
  "schema_version": "v1",
  "name_for_model": "fiskaly",
  "description_for_model": "fiskaly provides fiscal compliance APIs...",
  "api": {
    "type": "openapi",
    "url": "https://workspace.fiskaly.com/specs/sign-de-v2.json"
  }
}

Acceso de rastreadores

La configuración de robots.txt permite a los rastreadores LLM acceder a todos los endpoints de documentación y legibles por máquinas. Los rastreadores web estándar tienen permiso para páginas de documentación, archivos de especificaciones y endpoints de datos estructurados.

💡Tip

Prefiera el servidor MCP sobre la obtención HTTP directa cuando trabaje en Claude Code o Cursor. El servidor MCP proporciona los mismos datos a través de llamadas de herramientas estructuradas con búsqueda y filtrado integrados. Consulta la guía del servidor MCP.