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#
- La URL base de pruebas es
https://api-sandbox.mynexusapi.comy la de producción,https://api.mynexusapi.com. El ambiente lo define la URL; nunca se envía en el cuerpo. - Toda llamada a
/v1lleva la cabeceraX-Api-Keyy 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 elcodEstado3010 (ip_no_autorizada). El sandbox acepta cualquier IP. Una API Key ausente, inválida o revocada responde 401 con elcodEstado3009 (credenciales_invalidas). - El primer paso es
GET /v1/contexto.contribuyentes[].identificaciones 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 eninfoTributaria.ruc. - 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) oretenciones(07), conContent-Type: application/jsonoapplication/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}/validaraplica las mismas reglas sin emitir, sinIdempotency-Keyy 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 elcodEstado3002 (comprobante_invalido). Es opcional; conviene para revisar lo que generes automáticamente antes de pedir confirmación. - El cuerpo lleva
origenReferencia,referenciaExterna,infoTributaria(conruc,estab,ptoEmiysecuencialopcional),infoy la colección del tipo:detalles,motivos,destinatariosodocsSustento. No incluyastipoDocumento: el tipo va en la ruta. - No envíes
claveAcceso,ambiente,tipoEmision,versionniformato, porque son campos desconocidos y responden 422. Si omitessecuencialo envías"000000000", asignamos el siguiente. - La cabecera
Idempotency-Keyes obligatoria, en ASCII y con un máximo de 128 caracteres; si falta, la API responde 400 con elcodEstado3003 (solicitud_invalida). La misma clave con el mismo cuerpo devuelve el mismoidOperaciony el estado actual de la operación, y la misma clave con otro cuerpo responde 409 con elcodEstado3005 (conflicto_idempotencia). La clave se recuerda 7 días por integración y ambiente. - La emisión responde
202 Acceptedcon un cuerpo plano que traeestado(normalmenterecibido;autorizadosi la autorización ya se conoce),codEstado(1001; 1002 si ya traeclaveAcceso; 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 cabeceraLocation),ambiente,tipoDocumento,numeroDocumento,referenciaExterna,claveAcceso(puede sernull),fhRecibidoyfhAutorizacion, junto con la cabeceraX-Correlation-Id. Un 202 no es una autorización salvo conautorizado(2001); un rechazo definitivo ya conocido responde422con el mismo cuerpo. La cabecera opcionalX-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. - El seguimiento es
GET /v1/operaciones/{idOperacion}y devuelve la misma forma que el 202; se consulta mientrasestadosearecibido(codEstado1001 o 1002). Los estados finales sonautorizado(2001),rechazado(3xxx),rechazo_configuracion(4xxx),error(5xxx) ycancelado(6001), y todos salvoautorizadotraenmsgErrory el detalle enerrores; en un rechazo del SRI (3001),errorestrae su mensaje. El resultado también llega por los webhooksdocument.authorized,document.rejectedydocument.failed, que traen los mismosestado,codEstado,msgErroryerrores;document.failedindica que no se pudo emitir y no es un rechazo del SRI. - Los archivos se descargan con
GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride(PDF) y/xml, usando laclaveAccesoreal de 49 dígitos que devuelve el seguimiento. - El error tiene un cuerpo plano
{"estado","codEstado","msgError","errores"}, y el de la emisión tiene además los campos del 202 ennull.codEstadoes un número estable de 4 dígitos cuyo primer dígito es elestado;erroresviene siempre, con detalle en los errores de validación y como[]en el resto. Decide por el estado HTTP ycodEstado, no pormsgError. El catálogo está en Errores. - Estos códigos se corrigen y no se reintentan: 3003
solicitud_invalida(HTTP 400, cabeceras o JSON), 3002comprobante_invalido(HTTP 422, campos o regla fiscal; consume 1 documento como intento), 3006cuerpo_excedido(HTTP 413), 3009credenciales_invalidas(HTTP 401, API Key ausente o inválida), 3010ip_no_autorizada(HTTP 403, IP no permitida), 3011acceso_denegado(HTTP 403, permiso), 3004comprobante_duplicado(HTTP 409) y 3005conflicto_idempotencia(HTTP 409, misma clave con otro cuerpo). - Estos códigos se reintentan con espera y la misma
Idempotency-Key: 5005limite_solicitudes(HTTP 429; respetaRetry-After), 5001error_interno(HTTP 500), 5002servicio_no_disponible, 5003error_dependenciay 5004tiempo_agotado(HTTP 503, 502 y 504), y también los cortes de red. 4004cupo_agotado(HTTP 429) indica que no queda cupo y no se resuelve reintentando. - 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
canceladono lo consume. Sin API Key puedes consultarGET /estado(estado del servicio, hasta 60 consultas por minuto por IP) y con ellaGET /v1/catalogosyGET /v1/catalogos/{nombre}(catálogos del SRI). - Cada webhook lleva la firma
Ecuafact-Signature: t=<epoch>,v1=<hmac_sha256_hex>, calculada sobret + "." + cuerpo_crudocon los bytes UTF-8 del secreto como clave, y además las cabeceras de Standard Webhooks (webhook-id,webhook-timestampywebhook-signature), que verifican las librerías oficiales del estándar con el secreto, con o sin el prefijowhsec_. Basta con verificar una de las dos. Los duplicados se descartan poreventType+resourceId, o porwebhook-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#
- 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.
- Cita la fuente. Usa
source_urly, en temas fiscales o de contrato,last_updated. - Rotula el ambiente de pruebas. Todo ejemplo contra
api-sandbox.mynexusapi.comlleva "Ambiente de pruebas: sin validez fiscal". - Confirma antes de emitir. Muestra el comprobante y pide confirmación
explícita al usuario; en reintentos reutiliza la misma
Idempotency-Key. - No expongas secretos. No imprimas, registres ni escribas en archivos
versionados la API Key ni el secreto de webhooks; usa
ECUAFACT_API_KEYyECUAFACT_WEBHOOK_SECRET. La API Key solo se usa desde el backend, nunca en un navegador o una app móvil. - No uses datos fiscales reales en ejemplos. Usa los de
Datos de prueba (
0123456789001y la clave de acceso de ejemplo). - Distingue rechazo de notificación. Un 4xx de validación o una
operación con
estadorechazadoorechazo_configuracionse corrigen y se emiten con unaIdempotency-Keynueva; no se reintentan iguales. UnerrorconcodEstado5007 (resultado_no_confirmado) o 5001 (error_interno) es una notificación: no emitas de nuevo y pide al usuario que escriba a soporte con elidOperacion. - Respeta
Retry-Afteren las respuestas 429 y 503. - 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.
- 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#
- MCP y asistentes: configura el servidor MCP en tu cliente.
- Skill para asistentes de IA: instala el conocimiento de la API en el asistente.
- Primeros pasos: sigue el flujo completo de la API Key al RIDE, con ejemplos.