<!-- source_url: https://docs.mynexusapi.com/v1/guias/agentes | last_updated: 2026-11-19 -->

# 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](/v1/guias/primeros-pasos), [SDK](/v1/guias/sdk), [CLI](/v1/guias/cli)
y [MCP](/v1/guias/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](/v1/guias/errores#catalogo-de-codestado).
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](/v1/guias/primeros-pasos),
[Comprobantes electrónicos](/v1/guias/emision), [Errores](/v1/guias/errores),
[Límites](/v1/guias/limites) y [Webhooks](/v1/guias/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](/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](/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](/api/openapi.json) | Contrato de la API en formato máquina. | Generar clientes o validar campos. |
| [Catálogo de servicios](/.well-known/api-catalog) | Enlaces a OpenAPI, documentación y versiones (RFC 9727). | Descubrimiento automático. |
| [Versiones del contrato](/.well-known/api-versions.json) | Versión vigente, fechas y retiro. | Saber si una versión sigue vigente. |
| [sitemap.xml](/sitemap.xml) | URLs de todas las guías. | Rastreo. |
| [Versionado](/v1/guias/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](/llms-full.txt). En [llms.txt](/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](/v1/guias/mcp).

## Skill

Puedes cargar en el asistente el conocimiento de la API con nuestro skill, un
paquete descargable, [`ecuafact.zip`](/downloads/v1/skills/ecuafact.zip), con
`SKILL.md` y la carpeta `reference/`. Su instalación se explica en
[Skill para asistentes de IA](/v1/guias/skill).

## CLI

Con nuestro [CLI](/v1/guias/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](/v1/guias/cli-referencia#codigos-de-salida).

## 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](/v1/guias/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](/api/openapi.json), no lo uses aunque lo veas en código de
    terceros o en una copia guardada.

## Siguientes pasos

- [MCP y asistentes](/v1/guias/mcp): configura el servidor MCP en tu cliente.
- [Skill para asistentes de IA](/v1/guias/skill): instala el conocimiento de la API en el asistente.
- [Primeros pasos](/v1/guias/primeros-pasos): sigue el flujo completo de la API Key al RIDE, con ejemplos.
