Instrucciones para agentes de IA

Guia para asistentes (Claude, ChatGPT, Copilot, Cursor y agentes propios) que integran o consumen esta API. Describe como obtener la documentacion vigente, como ejecutar acciones y que reglas seguir.

Documentacion para agentes#

  • llms.txt: indice con la version .md de cada guia y una descripcion por entrada.
  • llms-full.txt: toda la documentacion en un archivo.
  • Markdown por pagina: agrega .md a cualquier guia (/v1/guias/emision-01.md) o envia Accept: text/markdown.
  • sitemap.xml: URLs de todas las guias.
  • OpenAPI: el contrato de la API en formato maquina.
  • Catalogo de servicios: donde estan el OpenAPI, la documentacion y el calendario de versiones (RFC 9727).
  • Versiones del contrato: version vigente, fechas y retiro.
  • Versionado: politica y cabecera X-Api-Version.

Cuando necesites el detalle actualizado, reconsulta la version .md de la guia; no dependas de una copia cacheada.

Acciones (MCP)#

  • Endpoint: {BaseUrl}/mcp (Streamable HTTP).
  • Autenticacion: cabecera X-Api-Key; reenviala por peticion, nunca la guardes.
  • Herramientas de lectura y escritura; la emision exige confirmacion e Idempotency-Key.
  • Detalle en MCPs y asistentes.

Skill#

Paquete de conocimiento descargable (SKILL.md + recursos) para cargar en el asistente. Detalle en Skill para asistentes de IA.

Reglas para agentes#

  1. No inventes contrato. Endpoints, campos y codigos salen de esta documentacion; ante duda, lee la guia .md o usa las herramientas de consulta.
  2. Cita la fuente canonica. Usa la URL canonica de la guia (https://docsapi.ecuafact.com/v1/guias/{slug}) y, si tu respuesta depende de un detalle fiscal o de contrato, la fecha last_updated de esa guia.
  3. El sandbox no tiene validez fiscal. Rotula cualquier ejemplo de pruebas.
  4. Confirma antes de emitir. Pide confirmacion explicita al usuario y reutiliza la misma Idempotency-Key en reintentos.
  5. No expongas secretos. No imprimas ni registres la API Key.
  6. Deduplica webhooks por eventType + resourceId; no asumas orden.
  7. Distingue rechazo de notificacion; no reintentes un 4xx sin corregir.
  8. Respeta Retry-After en 429/503.

Metadatos#

Cada guia expone dos campos citables:

  • source_url: la URL canonica de la guia (.../v1/guias/{slug}).
  • last_updated: la fecha (aaaa-mm-dd) del ultimo cambio de esa guia.

Aparecen en el encabezado de la version .md de cada guia, en la entrada correspondiente de llms.txt y junto a cada seccion de llms-full.txt. Cita la URL canonica siempre; agrega la fecha cuando tu respuesta dependa de un detalle fiscal o de contrato. La version del contrato (X-Api-Version) y su calendario estan en Versionado.

Siguientes pasos#

No se pudo completar la operacion. Recargar ✕