Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Instrucciones para agentes de IA

Lo esencial del contrato de la API de Ecuafact y las reglas que debe seguir un agente de IA que integra o usa la facturación electrónica.

Si configuras un agente de IA para trabajar con nuestros servicios de facturación, puedes darle esta página como punto de partida. Sirve para un asistente de programación que genera tu integración, un agente conectado a nuestro servidor MCP o un script que usa nuestro CLI. Si quieres un texto listo para pegar en tu agente, busca la sección «Para agentes» de las guías de Primeros pasos, SDK, CLI y MCP.

Encontrarás el contrato en 15 líneas, los recursos pensados para agentes y cómo citarlos, lo que tu agente puede hacer con el MCP, el skill o el CLI, y las reglas que debe respetar siempre.

Contrato en 15 líneas#

  1. La URL base de pruebas es https://api-sandbox.mynexusapi.com y la de producción, https://api.mynexusapi.com. El ambiente lo define la URL; nunca se envía en el cuerpo.
  2. Toda llamada a /v1 lleva la cabecera X-Api-Key y se hace solo desde el backend. Una API Key cubre todos los contribuyentes autorizados de la integración, y en producción la IP de origen debe estar registrada; si no lo está, la API responde 403 con el codEstado 3010 (ip_no_autorizada). El sandbox acepta cualquier IP. Una API Key ausente, inválida o revocada responde 401 con el codEstado 3009 (credenciales_invalidas).
  3. El primer paso es GET /v1/contexto. contribuyentes[].identificacion es la identificación completa del contribuyente (su RUC de 13 dígitos o una identificación de 5 a 13 dígitos) y va igual en las rutas y en infoTributaria.ruc.
  4. La emisión es POST /v1/contribuyentes/{identificacion}/{ruta} y el tipo lo fija la ruta: facturas (01), liquidaciones-compra (03), notas-credito (04), notas-debito (05), guias-remision (06) o retenciones (07), con Content-Type: application/json o application/xml. Si envías el XML del SRI, se aplican las mismas reglas que al JSON y la firma que traiga se ignora. El cuerpo admite como máximo 2 MiB. POST /v1/contribuyentes/{identificacion}/{ruta}/validar aplica las mismas reglas sin emitir, sin Idempotency-Key y sin consumir cupo: responde 200 con {"valido":true,"errores":[]} si el comprobante cumple todas las reglas, o el error que daría la emisión, por ejemplo 422 con el codEstado 3002 (comprobante_invalido). Es opcional; conviene para revisar lo que generes automáticamente antes de pedir confirmación.
  5. El cuerpo lleva origenReferencia, referenciaExterna, infoTributaria (con ruc, estab, ptoEmi y secuencial opcional), info y la colección del tipo: detalles, motivos, destinatarios o docsSustento. No incluyas tipoDocumento: el tipo va en la ruta.
  6. No envíes claveAcceso, ambiente, tipoEmision, version ni formato, porque son campos desconocidos y responden 422. Si omites secuencial o envías "000000000", asignamos el siguiente.
  7. La cabecera Idempotency-Key es obligatoria, en ASCII y con un máximo de 128 caracteres; si falta, la API responde 400 con el codEstado 3003 (solicitud_invalida). La misma clave con el mismo cuerpo devuelve el mismo idOperacion y el estado actual de la operación, y la misma clave con otro cuerpo responde 409 con el codEstado 3005 (conflicto_idempotencia). La clave se recuerda 7 días por integración y ambiente.
  8. La emisión responde 202 Accepted con un cuerpo plano que trae estado (normalmente recibido; autorizado si la autorización ya se conoce), codEstado (1001; 1002 si ya trae claveAcceso; 2001 si ya está autorizado; en los tres casos la respuesta es 202), errores ([] salvo un resultado final con detalle), idOperacion, urlEstado (la URL absoluta del seguimiento, igual a la cabecera Location), ambiente, tipoDocumento, numeroDocumento, referenciaExterna, claveAcceso (puede ser null), fhRecibido y fhAutorizacion, junto con la cabecera X-Correlation-Id. Un 202 no es una autorización salvo con autorizado (2001); un rechazo definitivo ya conocido responde 422 con el mismo cuerpo. La cabecera opcional X-Additional-Info, en ASCII imprimible y con un máximo de 256 caracteres, se asocia a tu solicitud para soporte y no cambia la respuesta.
  9. El seguimiento es GET /v1/operaciones/{idOperacion} y devuelve la misma forma que el 202; se consulta mientras estado sea recibido (codEstado 1001 o 1002). Los estados finales son autorizado (2001), rechazado (3xxx), rechazo_configuracion (4xxx), error (5xxx) y cancelado (6001), y todos salvo autorizado traen msgError y el detalle en errores; en un rechazo del SRI (3001), errores trae su mensaje. El resultado también llega por los webhooks document.authorized, document.rejected y document.failed, que traen los mismos estado, codEstado, msgError y errores; document.failed indica que no se pudo emitir y no es un rechazo del SRI.
  10. Los archivos se descargan con GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride (PDF) y /xml, usando la claveAcceso real de 49 dígitos que devuelve el seguimiento.
  11. El error tiene un cuerpo plano {"estado","codEstado","msgError","errores"}, y el de la emisión tiene además los campos del 202 en null. codEstado es un número estable de 4 dígitos cuyo primer dígito es el estado; errores viene siempre, con detalle en los errores de validación y como [] en el resto. Decide por el estado HTTP y codEstado, no por msgError. El catálogo está en Errores.
  12. Estos códigos se corrigen y no se reintentan: 3003 solicitud_invalida (HTTP 400, cabeceras o JSON), 3002 comprobante_invalido (HTTP 422, campos o regla fiscal; consume 1 documento como intento), 3006 cuerpo_excedido (HTTP 413), 3009 credenciales_invalidas (HTTP 401, API Key ausente o inválida), 3010 ip_no_autorizada (HTTP 403, IP no permitida), 3011 acceso_denegado (HTTP 403, permiso), 3004 comprobante_duplicado (HTTP 409) y 3005 conflicto_idempotencia (HTTP 409, misma clave con otro cuerpo).
  13. Estos códigos se reintentan con espera y la misma Idempotency-Key: 5005 limite_solicitudes (HTTP 429; respeta Retry-After), 5001 error_interno (HTTP 500), 5002 servicio_no_disponible, 5003 error_dependencia y 5004 tiempo_agotado (HTTP 503, 502 y 504), y también los cortes de red. 4004 cupo_agotado (HTTP 429) indica que no queda cupo y no se resuelve reintentando.
  14. Los límites son 200 solicitudes por minuto por integración (60 en un sandbox), 20 autenticaciones fallidas por minuto por IP, una profundidad JSON de 32 y un cuerpo de 1 MiB fuera de la emisión. Cada comprobante autorizado o rechazado consume un documento de tu cupo, y uno cancelado no lo consume. Sin API Key puedes consultar GET /estado (estado del servicio, hasta 60 consultas por minuto por IP) y con ella GET /v1/catalogos y GET /v1/catalogos/{nombre} (catálogos del SRI).
  15. Cada webhook lleva la firma Ecuafact-Signature: t=<epoch>,v1=<hmac_sha256_hex>, calculada sobre t + "." + cuerpo_crudo con los bytes UTF-8 del secreto como clave, y además las cabeceras de Standard Webhooks (webhook-id, webhook-timestamp y webhook-signature), que verifican las librerías oficiales del estándar con el secreto, con o sin el prefijo whsec_. Basta con verificar una de las dos. Los duplicados se descartan por eventType + resourceId, o por webhook-id.

El detalle de cada punto está en Primeros pasos, Comprobantes electrónicos, Errores, Límites y Webhooks.

Documentación para agentes#

La documentación se publica también en formatos pensados para que un agente la lea y la cite.

Recurso Qué contiene Uso recomendado
llms.txt Resumen esencial del contrato e índice con el enlace .md de cada guía, su descripción y su fecha de actualización. Punto de entrada para decidir qué guía leer.
llms-full.txt El mismo resumen y todas las guías completas en un archivo, en el orden del menú. Cargar el contexto completo de una vez.
/v1/guias/{slug}.md Markdown de una guía (por ejemplo, /v1/guias/emision-01.md). También responde a Accept: text/markdown en la URL de la guía. Leer el detalle vigente de un tema.
OpenAPI Contrato de la API en formato máquina. Generar clientes o validar campos.
Catálogo de servicios Enlaces a OpenAPI, documentación y versiones (RFC 9727). Descubrimiento automático.
Versiones del contrato Versión vigente, fechas y retiro. Saber si una versión sigue vigente.
sitemap.xml URLs de todas las guías. Rastreo.
Versionado Política de versiones y cabecera X-Api-Version. Fijar una versión del contrato.

Cuando necesites un dato exacto, vuelve a leer la versión .md de la guía en lugar de confiar en una copia guardada, porque la guía en línea es la vigente.

Metadatos citables#

Cada guía expone dos campos para que puedas citarla:

Campo Contenido
source_url URL canónica de la guía: https://docs.mynexusapi.com/v1/guias/{slug}.
last_updated Fecha (aaaa-mm-dd) del último cambio de la guía.

Los dos campos aparecen como un comentario al inicio de la versión .md de cada guía (<!-- source_url: ... | last_updated: ... -->) y antes de cada guía en llms-full.txt. En llms.txt, cada entrada enlaza la versión .md y termina con (actualizado: aaaa-mm-dd). Cita siempre source_url, y agrega last_updated cuando la respuesta dependa de un detalle fiscal o de contrato.

Acciones con MCP#

Con nuestro servidor MCP, un asistente puede consultar y emitir mediante herramientas. Cada ambiente tiene su endpoint:

Ambiente Endpoint (Streamable HTTP)
Pruebas https://mcp-sandbox.mynexusapi.com/mcp
Producción https://mcp.mynexusapi.com/mcp

El acceso al servidor MCP es con OAuth 2.1 (Authorization: Bearer) y no con la API Key. Un asistente se conecta con la URL del endpoint y la persona aprueba sus permisos y sus RUC en el portal del cliente; un sistema sin persona usa un bot con client_credentials. El agente solo ve las herramientas y los RUC que se le concedieron.

Tipo Herramientas
Lectura obtener_contexto, obtener_consumo, listar_operaciones, consultar_operacion, descargar_archivo, validar_identificacion, consultar_contribuyente, buscar_contribuyentes, listar_establecimientos, decodificar_clave_acceso, listar_catalogos, obtener_catalogo y obtener_estado_servicio.
Escritura validar_comprobante, que valida sin emitir y es opcional, y emitir_comprobante, que exige confirmar=true e idempotencyKey.
Perfil y webhooks Con los permisos que concedas en la pantalla de consentimiento: obtener_perfil, actualizar_perfil, actualizar_logo_perfil y las herramientas de destinos y entregas de webhooks. Las que cambian algo exigen confirmar=true.

En validar_comprobante y emitir_comprobante, el parámetro tipo (factura, liquidacion, nota-credito, nota-debito, guia o retencion) elige la ruta del tipo, y la estructura es el cuerpo exacto de ese tipo, sin ningún campo de tipo: si trae infoTributaria.tipoDocumento, la API responde el error de validación 3002 (comprobante_invalido) con el campo en errores.

La configuración de cada cliente, los permisos y los parámetros de cada herramienta están en MCP y asistentes.

Skill#

Puedes cargar en el asistente el conocimiento de la API con nuestro skill, un paquete descargable, ecuafact.zip, con SKILL.md y la carpeta reference/. Su instalación se explica en Skill para asistentes de IA.

CLI#

Con nuestro CLI instalado, el agente puede consultar, emitir y descargar comprobantes desde la terminal. ecuafact schema describe todos los comandos en JSON, y cuando el CLI no se ejecuta en una terminal, también responde en JSON. La API Key va en ECUAFACT_API_KEY y nunca como argumento. Agrega --confirmar produccion solo cuando el usuario lo pidió para ese envío. Los códigos de salida para interpretar el resultado están en la Referencia de comandos.

Reglas para agentes#

  1. No inventes contrato. Endpoints, campos, códigos y límites salen de esta documentación. Si no encuentras un dato, dilo y enlaza la guía más cercana.
  2. Cita la fuente. Usa source_url y, en temas fiscales o de contrato, last_updated.
  3. Rotula el ambiente de pruebas. Todo ejemplo contra api-sandbox.mynexusapi.com lleva "Ambiente de pruebas: sin validez fiscal".
  4. Confirma antes de emitir. Muestra el comprobante y pide confirmación explícita al usuario; en reintentos reutiliza la misma Idempotency-Key.
  5. No expongas secretos. No imprimas, registres ni escribas en archivos versionados la API Key ni el secreto de webhooks; usa ECUAFACT_API_KEY y ECUAFACT_WEBHOOK_SECRET. La API Key solo se usa desde el backend, nunca en un navegador o una app móvil.
  6. No uses datos fiscales reales en ejemplos. Usa los de Datos de prueba (0123456789001 y la clave de acceso de ejemplo).
  7. Distingue rechazo de notificación. Un 4xx de validación o una operación con estado rechazado o rechazo_configuracion se corrigen y se emiten con una Idempotency-Key nueva; no se reintentan iguales. Un error con codEstado 5007 (resultado_no_confirmado) o 5001 (error_interno) es una notificación: no emitas de nuevo y pide al usuario que escriba a soporte con el idOperacion.
  8. Respeta Retry-After en las respuestas 429 y 503.
  9. Verifica los webhooks. Verifica la firma sobre el cuerpo crudo, responde un 2xx después de guardar el evento y no asumas un orden de llegada.
  10. No uses funciones fuera del contrato público. Si un endpoint, campo o parámetro no aparece en esta documentación ni en el OpenAPI, no lo uses aunque lo veas en código de terceros o en una copia guardada.

Siguientes pasos#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.