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

# MCP y asistentes

Conecta Claude, ChatGPT, Cursor, VS Code o tu propio agente al servidor MCP de Ecuafact para consultar y emitir comprobantes con permisos OAuth.

Puedes conectar tu agente de IA con nuestros servicios de facturación mediante
nuestro servidor MCP, para que consulte tu cuenta, busque comprobantes,
descargue archivos y, si se lo permites, emita en tu nombre. Tú le pides algo
en lenguaje natural y el asistente lo hace por ti, con los mismos datos y las
mismas reglas que tu integración.

Esta página explica cómo conectar cada asistente o un sistema propio, qué
permisos puedes darle, qué herramientas recibe y cómo revocar su acceso. Al
terminar tendrás un agente conectado al ambiente de pruebas que responde con los
datos de tu cuenta.

## Para agentes

Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.

Pega este prompt en un agente de programación con acceso a la terminal:

```text
Conecta el servidor MCP de Ecuafact de mi cuenta en este agente y verifica la conexión en el ambiente de pruebas. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, puedes instalarla con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/mcp.md antes de escribir código; no inventes campos. Usa el endpoint https://mcp-sandbox.mynexusapi.com/mcp con OAuth: en Claude Code, claude mcp add --transport http ecuafact https://mcp-sandbox.mynexusapi.com/mcp y luego /mcp > Authenticate; en otro cliente, agrégalo como servidor remoto con esa URL. No uses mi API Key ni pidas tokens: la autorización la apruebo yo en el navegador, en el Portal del Cliente, y nunca debes pegar ni imprimir credenciales en el chat. Si el cliente no admite OAuth remoto, dímelo en lugar de improvisar. Cuando esté conectado, llama a obtener_contexto y confirma que solo ves los RUC que autoricé; después arma una factura con los datos de prueba de la guía, valídala con validar_comprobante, muéstrame el comprobante y espera mi confirmación expresa antes de emitir_comprobante con confirmar=true y una idempotencyKey estable; sigue el resultado con consultar_operacion hasta un estado final. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide siempre por estado y codEstado (numérico), usa urlEstado tal cual (URL absoluta) y lee errores como arreglo. Ejecuta el flujo e informa solo el RUC usado, el estado, el codEstado y la claveAcceso, y cualquier acción que yo deba hacer.
```

## Conceptos

**MCP** (Model Context Protocol) es un estándar abierto para que un asistente de
IA use herramientas externas. Nuestro servidor MCP le ofrece a tu asistente
herramientas como `obtener_contexto` o `emitir_comprobante`, y el asistente
decide cuándo usarlas y te muestra el resultado. Cada herramienta equivale a un
endpoint de la API que documentan las guías, así que las reglas, los límites y
los errores son los mismos que en tu integración.

El acceso es con **OAuth 2.1** y no con tu API Key. Cada agente conectado recibe
su propio permiso, que tú eliges al conectarlo y que define dos cosas:

- **Qué puede hacer.** Puede consultar, emitir o hacer
  consultas al SRI, según los [permisos](#permisos) que le des.
- **Sobre qué RUC.** Puede trabajar con todos los
  [contribuyentes](/v1/guias/glosario) de tu cuenta o solo con los que marques.

Un agente nunca ve datos de otra cuenta ni de un RUC que no le diste. Puedes
revocar su acceso en cualquier momento desde el portal del cliente, en
**Integración > Agentes IA**, y el agente deja de funcionar en menos de un
minuto.

Puedes conectar un agente de dos formas, según quién lo use:

| Quién usa el agente | Cómo se autoriza | Sección |
|---|---|---|
| Una persona (asistente de chat, editor, terminal) | Inicias sesión en el portal del cliente y apruebas los permisos. | [Asistentes](#asistentes) |
| Un sistema sin persona (automatización, bot, script) | Un propietario crea un **bot** en el portal y el sistema pide sus tokens con `client_credentials`. | [Bots](#bots) |

## Endpoints

Nuestro servidor MCP es remoto y usa el transporte **Streamable HTTP**. Cada
ambiente tiene su propio endpoint; el portal de autorización es el mismo, el de
producción.

| Ambiente | Endpoint MCP | Portal donde se autoriza |
|---|---|---|
| Pruebas | `https://mcp-sandbox.mynexusapi.com/mcp` | `https://portal.mynexusapi.com` |
| Producción | `https://mcp.mynexusapi.com/mcp` | `https://portal.mynexusapi.com` |

El MCP de pruebas solo se autoriza mientras la cuenta está en estado sandbox.
Al pasar a producción, la conexión se revoca y debes conectar el MCP de
producción. Un agente autorizado en pruebas no funciona en producción ni al
revés.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Empieza siempre con
> `https://mcp-sandbox.mynexusapi.com/mcp`.

## Servidor de documentación

Además del servidor de tu cuenta, publicamos un servidor MCP de documentación
en `https://docs.mynexusapi.com/mcp`. Es público y no pide cuenta, API Key ni
autorización: solo lee esta documentación, así que sirve para que el asistente
de tu editor escriba tu integración consultando las guías vigentes en lugar de
lo que recuerda. No opera ninguna cuenta; para emitir o consultar tus
comprobantes, conecta el servidor de tu cuenta como explican las secciones
siguientes.

Ofrece seis herramientas, todas de solo lectura:

| Herramienta | Parámetros | Para qué sirve |
|---|---|---|
| `listar_guias` | - | Índice de las guías por tema, con su slug, una descripción corta y su URL. |
| `buscar_documentacion` | `consulta`; opcional `maximo` (1 a 20, por defecto 8) | Guías relevantes para lo que buscas, con un fragmento y su URL. |
| `leer_guia` | `slug` (por ejemplo `emision-01`, o la URL de la guía); opcional `seccion` | La guía en Markdown. Con `seccion` devuelve solo esa parte, lo que conviene en las guías largas, como las de los SDK. |
| `explicar_error` | `codEstado` (el número de la respuesta, por ejemplo `3002`, o su nombre, como `comprobante_invalido`) | Las filas del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado) para ese código: `estado`, estado HTTP, `msgError`, cuándo ocurre, qué hacer y si se reintenta. También explica los [códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion), como el 3001 de un rechazo del SRI. |
| `ejemplo_comprobante` | `tipo` (`01`, `03`, `04`, `05`, `06` o `07`, o su nombre) | Un JSON de ejemplo listo para el POST HTTP de ese tipo, listo para `estructura`: es el cuerpo exacto del esquema de ese tipo. Incluye el enlace a su guía. |
| `consultar_referencia` | opcionales `ruta` y `metodo` | Sin parámetros, la lista de endpoints; con una ruta, sus parámetros, su cuerpo, sus respuestas y los esquemas que usa, tomados del [OpenAPI](/v1/guias/colecciones). |

Para conectarlo en Claude Code:

```bash
claude mcp add --transport http ecuafact-docs https://docs.mynexusapi.com/mcp
```

En Cursor, VS Code u otro cliente, agrega un servidor remoto de tipo HTTP con
esa URL, igual que en las secciones de cada asistente, pero sin el paso de
autorización. Puedes tener conectados a la vez el servidor de documentación y
el de tu cuenta.

Cada IP puede hacer hasta 300 consultas por minuto. Si las superas, el servidor
responde `429` con la cabecera `Retry-After: 60` y el mensaje
`Demasiadas consultas. Espera 60 segundos.`

## Requisitos

- [ ] Un usuario del portal del cliente del mismo ambiente que el endpoint. Si
      no tienes cuenta de pruebas, [crea un sandbox](/v1/guias/sandbox).
- [ ] Permiso para conectar agentes. El rol **propietario** lo tiene; para otros
      roles, un propietario agrega **Autorizar agentes IA (consulta)** en
      **Equipo > Roles**. Para que un agente pueda emitir o enviar correos hace
      falta además **Autorizar agentes IA a emitir y enviar correos**.
- [ ] Un cliente MCP que admita servidores remotos con OAuth, como Claude,
      ChatGPT, Claude Code, Cursor o VS Code con GitHub Copilot. Si tu cliente
      solo admite servidores locales, necesitas el puente `mcp-remote`, que
      requiere Node.js 18 o superior.

A diferencia de la API, no necesitas registrar una IP.

## Asistentes

Si quien usa el agente eres tú o alguien de tu equipo, puedes conectarlo solo
con la URL del endpoint. El cliente MCP abre tu navegador en el portal del
cliente, inicias sesión y apruebas los permisos. Todos los ejemplos usan el endpoint de pruebas; para
producción, cambia la URL por `https://mcp.mynexusapi.com/mcp`.

### Claude y Claude Desktop

1. Abre **Configuración > Conectores > Agregar conector personalizado**.
2. Escribe un nombre (por ejemplo, `Ecuafact`) y la URL
   `https://mcp-sandbox.mynexusapi.com/mcp`.
3. Pulsa **Conectar** y se abrirá el portal del cliente. Inicia sesión, elige
   los permisos y los RUC y pulsa **Permitir**.

### ChatGPT

1. Activa el modo desarrollador en **Configuración > Aplicaciones y conectores >
   Configuración avanzada**.
2. En **Aplicaciones y conectores**, pulsa **Crear**, escribe la URL
   `https://mcp-sandbox.mynexusapi.com/mcp` y elige **OAuth** como autenticación.
3. Autoriza en el portal del cliente como en el paso 3 de Claude.

### Claude Code

Registra el servidor y autorízalo desde Claude Code:

```bash
claude mcp add --transport http ecuafact https://mcp-sandbox.mynexusapi.com/mcp
```

Dentro de Claude Code, escribe `/mcp`, elige `ecuafact` y pulsa
**Authenticate**; se abre el navegador para que apruebes los permisos. Si
quieres compartir la configuración con tu equipo, crea `.mcp.json` en la raíz
del proyecto. Cada persona autoriza después su propio acceso.

```json
{
  "mcpServers": {
    "ecuafact": {
      "type": "http",
      "url": "https://mcp-sandbox.mynexusapi.com/mcp"
    }
  }
}
```

### Cursor

Crea `.cursor/mcp.json` en tu proyecto, o `~/.cursor/mcp.json` si lo quieres
para todos tus proyectos, y pulsa **Login** junto al servidor en
**Settings > MCP**.

```json
{
  "mcpServers": {
    "ecuafact": {
      "url": "https://mcp-sandbox.mynexusapi.com/mcp"
    }
  }
}
```

### VS Code

Crea `.vscode/mcp.json` con `servers` como clave raíz. Al iniciar el servidor,
VS Code te pide que lo autorices en el navegador.

```json
{
  "servers": {
    "ecuafact": {
      "type": "http",
      "url": "https://mcp-sandbox.mynexusapi.com/mcp"
    }
  }
}
```

### Clientes que solo admiten servidores locales

Para un cliente que solo admite servidores locales, `mcp-remote` hace de puente
y se encarga de la autorización; la primera vez, abre el navegador para que
apruebes los permisos. Este es un ejemplo para `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ecuafact": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-sandbox.mynexusapi.com/mcp"
      ]
    }
  }
}
```

### Verifica la conexión

Para comprobar que el asistente quedó conectado, sigue estos pasos:

1. Pide al asistente: "Usa la herramienta obtener_contexto de ecuafact".
2. Comprueba que responde con tu integración y **solo** con los RUC que
   autorizaste. Es el mismo JSON que devuelve
   [Contexto](/v1/guias/consulta-contexto).
3. Si ves un error, búscalo en [Errores](#errores).

El acceso de un asistente se mantiene mientras no lo revoques, porque el
cliente MCP renueva sus tokens por sí solo. Si cambias tu clave del portal,
pierdes el rol o el permiso, o tu usuario se desactiva, todos tus agentes dejan
de funcionar y tienes que volver a conectarlos.

## Bots

Si necesitas que un sistema tuyo, como una automatización o un script, use
nuestro servidor MCP sin una persona que inicie sesión, puedes crear un bot. Un
bot es un agente con sus propias credenciales.

### Crea el bot

1. En el portal del cliente, abre **Integración > Agentes IA** y pulsa
   **Crear bot**. Necesitas el rol propietario o el permiso **Revocar agentes
   de otros y administrar bots**.
2. Escribe un nombre, elige los permisos y los RUC y pulsa **Crear**.
3. Guarda el `client_id` y el `client_secret` que aparecen, porque el secreto
   **no se vuelve a mostrar**.

> [!WARNING]
> El `client_secret` da el mismo acceso que el bot. Guárdalo como un secreto de
> tu sistema, en una variable de entorno o en un gestor de secretos, y nunca en
> el código ni en un repositorio. Si se filtra, revoca el bot y crea otro.

Los ejemplos leen las credenciales de las variables de entorno
`ECUAFACT_BOT_ID` y `ECUAFACT_BOT_SECRET`.

### Pide un token

Pide un token al portal con `client_credentials` e indica el servidor MCP como
`resource`. El token dura **15 minutos** y los bots no reciben un token de
renovación, así que pide uno nuevo cuando venza.

```bash
curl -s -X POST "https://portal.mynexusapi.com/oauth/token" \
  -u "$ECUAFACT_BOT_ID:$ECUAFACT_BOT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "resource=https://mcp-sandbox.mynexusapi.com/mcp"
```

Si las credenciales son correctas, el portal responde `200 OK` con este cuerpo:

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "cuenta:leer comprobantes:leer"
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `access_token` | string | Token que envías en `Authorization: Bearer` al servidor MCP. |
| `token_type` | string | Siempre `Bearer`. |
| `expires_in` | número | Segundos de validez del token. Vale 900. |
| `scope` | string | Permisos del token, separados por espacio. Puedes pedir menos con el parámetro `scope`, pero nunca más que los del bot. |

### Llama a una herramienta

Con el token, llama al método `tools/call` del endpoint MCP:

```bash
TOKEN=$(curl -s -X POST "https://portal.mynexusapi.com/oauth/token" \
  -u "$ECUAFACT_BOT_ID:$ECUAFACT_BOT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "resource=https://mcp-sandbox.mynexusapi.com/mcp" | jq -r .access_token)

curl -s -X POST "https://mcp-sandbox.mynexusapi.com/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"obtener_contexto","arguments":{}}}'
```

Si todo funcionó, el servidor responde 200 con un evento `message`, cuyo
`result.content[0].text` es el JSON de [Contexto](/v1/guias/consulta-contexto)
con los RUC del bot.

Este es el mismo flujo con el SDK oficial de MCP para Python, versión 2 o
superior, que instalas con `pip install "mcp>=2" httpx`:

```python
import asyncio
import os

import httpx
from mcp import ClientSession
from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client

PORTAL = "https://portal.mynexusapi.com"
MCP = "https://mcp-sandbox.mynexusapi.com/mcp"


def pedir_token() -> str:
    respuesta = httpx.post(
        PORTAL + "/oauth/token",
        auth=(os.environ["ECUAFACT_BOT_ID"], os.environ["ECUAFACT_BOT_SECRET"]),
        data={"grant_type": "client_credentials", "resource": MCP},
    )
    print(respuesta.status_code)
    respuesta.raise_for_status()
    return respuesta.json()["access_token"]


async def main() -> None:
    cabeceras = {"Authorization": "Bearer " + pedir_token()}
    async with create_mcp_http_client(headers=cabeceras) as http:
        async with streamable_http_client(MCP, http_client=http) as (lectura, escritura, *_):
            async with ClientSession(lectura, escritura) as sesion:
                await sesion.initialize()
                resultado = await sesion.call_tool("obtener_contexto", {})
                print(resultado.content[0].text)


asyncio.run(main())
```

En Node.js, el ejemplo usa el SDK oficial, que instalas con
`npm install @modelcontextprotocol/sdk`:

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const PORTAL = "https://portal.mynexusapi.com";
const MCP = "https://mcp-sandbox.mynexusapi.com/mcp";

const credenciales = Buffer.from(
  `${encodeURIComponent(process.env.ECUAFACT_BOT_ID)}:${encodeURIComponent(process.env.ECUAFACT_BOT_SECRET)}`
).toString("base64");
const respuesta = await fetch(`${PORTAL}/oauth/token`, {
  method: "POST",
  headers: { Authorization: `Basic ${credenciales}`, "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ grant_type: "client_credentials", resource: MCP })
});
console.log(respuesta.status);
const { access_token } = await respuesta.json();

const transporte = new StreamableHTTPClientTransport(new URL(MCP), {
  requestInit: { headers: { Authorization: `Bearer ${access_token}` } }
});
const cliente = new Client({ name: "mi-bot", version: "1.0.0" });
await cliente.connect(transporte);
const resultado = await cliente.callTool({ name: "obtener_contexto", arguments: {} });
console.log(resultado.content[0].text);
await cliente.close();
```

En .NET, el ejemplo usa el SDK oficial, que instalas con
`dotnet add package ModelContextProtocol`:

```csharp
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol;

const string Portal = "https://portal.mynexusapi.com";
const string Mcp = "https://mcp-sandbox.mynexusapi.com/mcp";

using HttpClient http = new();
string credenciales = Convert.ToBase64String(Encoding.UTF8.GetBytes(
    Uri.EscapeDataString(Environment.GetEnvironmentVariable("ECUAFACT_BOT_ID")!) + ":" +
    Uri.EscapeDataString(Environment.GetEnvironmentVariable("ECUAFACT_BOT_SECRET")!)));
using HttpRequestMessage pedido = new(HttpMethod.Post, Portal + "/oauth/token")
{
    Content = new FormUrlEncodedContent(new Dictionary<string, string>
    {
        ["grant_type"] = "client_credentials",
        ["resource"] = Mcp
    })
};
pedido.Headers.Authorization = new AuthenticationHeaderValue("Basic", credenciales);
using HttpResponseMessage respuesta = await http.SendAsync(pedido);
Console.WriteLine((int)respuesta.StatusCode);
using JsonDocument json = JsonDocument.Parse(await respuesta.Content.ReadAsStringAsync());
string token = json.RootElement.GetProperty("access_token").GetString()!;

HttpClientTransport transporte = new(new HttpClientTransportOptions
{
    Endpoint = new Uri(Mcp),
    AdditionalHeaders = new Dictionary<string, string> { ["Authorization"] = "Bearer " + token }
});
await using McpClient cliente = await McpClient.CreateAsync(transporte);
CallToolResult resultado = await cliente.CallToolAsync("obtener_contexto", new Dictionary<string, object?>());
Console.WriteLine(((TextContentBlock)resultado.Content[0]).Text);
```

En PHP, el bot pide el token y llama a la herramienta directamente por HTTP:

```php
<?php
$portal = 'https://portal.mynexusapi.com';
$mcp = 'https://mcp-sandbox.mynexusapi.com/mcp';

$ch = curl_init($portal . '/oauth/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => rawurlencode(getenv('ECUAFACT_BOT_ID')) . ':' . rawurlencode(getenv('ECUAFACT_BOT_SECRET')),
    CURLOPT_POSTFIELDS => http_build_query(['grant_type' => 'client_credentials', 'resource' => $mcp]),
]);
$cuerpo = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
curl_close($ch);
$token = json_decode($cuerpo, true)['access_token'];

$ch = curl_init($mcp);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
        'Accept: application/json, text/event-stream',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/call',
        'params' => ['name' => 'obtener_contexto', 'arguments' => new stdClass()],
    ]),
]);
$respuesta = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $respuesta, PHP_EOL;
curl_close($ch);
```

## Permisos

Al conectar un agente eliges sus permisos. El permiso para consultar la cuenta
va siempre incluido, mientras que los permisos de escritura, los del perfil del
emisor y los de webhooks vienen desmarcados y los marcas solo si el agente los
necesita.

| Permiso | Alcance OAuth | Herramientas |
|---|---|---|
| Ver la cuenta (siempre) | `cuenta:leer` | `obtener_contexto`, `obtener_consumo`, `obtener_salud`, `obtener_estado_servicio` y las seis herramientas de [documentación](#documentacion) |
| Consultar comprobantes | `comprobantes:leer` | `listar_operaciones`, `consultar_operacion`, `descargar_archivo` |
| Consultas al SRI | `sri:consultar` | `consultar_contribuyente`, `buscar_contribuyentes`, `listar_establecimientos`, `validar_identificacion`, `decodificar_clave_acceso`, `listar_catalogos`, `obtener_catalogo` |
| Emitir comprobantes | `comprobantes:emitir` | `validar_comprobante`, `emitir_comprobante` |
| Enviar comprobantes por correo | `comprobantes:enviar` | Ninguna herramienta del servidor la usa por ahora; solo activa la confirmación en el portal descrita más abajo. |
| Ver el perfil | `perfil:leer` | `obtener_perfil` |
| Editar el perfil | `perfil:escribir` | `actualizar_perfil`, `actualizar_logo_perfil` |
| Ver destinos y entregas de webhooks | `webhooks:leer` | `listar_destinos_webhook`, `obtener_destino_webhook`, `listar_entregas_webhook`, `listar_intentos_entrega_webhook` |
| Gestionar destinos de webhooks | `webhooks:gestionar` | `crear_destino_webhook`, `actualizar_eventos_webhook`, `rotar_secreto_webhook`, `pausar_destino_webhook`, `reanudar_destino_webhook`, `deshabilitar_destino_webhook` |
| Probar destinos de webhooks | `webhooks:probar` | `probar_destino_webhook` |
| Reintentar entregas de webhooks | `webhooks:reintentar` | `reintentar_entrega_webhook` |
| Mantener el acceso | `offline_access` | No da herramientas; permite que el asistente renueve sus tokens sin pedirte que inicies sesión otra vez. |

La pantalla de permisos agrupa los permisos del perfil del emisor y los de
webhooks, cada uno con su propia casilla, y los ofrece aunque el agente no los
pida. Gobiernan las herramientas de
[perfil y destinos de webhooks](#perfil-y-destinos-de-webhooks). Con **Gestionar
destinos de webhooks** el agente puede ver el secreto de firma de cada destino que
crea o rota. Un bot recibe los permisos de comprobantes y consultas, pero no los de
perfil ni los de webhooks.

El agente solo ve en su lista las herramientas de los permisos que le diste. Si
le falta una, revoca el agente y vuelve a conectarlo marcando ese permiso. Para
quitarle permisos sin desconectarlo, usa **Editar permisos**, como se explica en
[Revocar o editar el acceso](#revocar-o-editar-el-acceso).

Si marcas emitir o enviar correos, la pantalla de permisos trae además la
casilla **Pedir mi confirmación para emitir y enviar correos**, marcada por
defecto. Con ella, cada emisión y cada envío del agente esperan tu aprobación en
el portal, como se explica en
[Confirmación en el portal](#confirmacion-en-el-portal).

## Herramientas

Cada herramienta devuelve datos de la API con los límites de respuesta descritos en esta guía. El parámetro `identificacion` es siempre
la `identificacion` que devuelve `obtener_contexto`, que es la identificación
completa del contribuyente (para un RUC, sus 13 dígitos), salvo en
`consultar_contribuyente`, donde es la cédula, el RUC o el pasaporte que
consultas. Si tu cuenta tiene varios RUC, el agente trabaja con uno por
llamada, así que pídele que use `obtener_contexto` y elija el que corresponda.

### Lectura

| Herramienta | Parámetros | Endpoint | Para qué sirve |
|---|---|---|---|
| `obtener_contexto` | - | `GET /v1/contexto` | Integración y RUC que autorizaste para este agente. Empieza siempre por aquí. |
| `obtener_consumo` | - | `GET /v1/consumo` | [Cupo](/v1/guias/consumo) de documentos disponible (suma de tus paquetes vigentes). |
| `listar_operaciones` | `identificacion`; opcionales `desde`, `hasta` (`yyyy-MM-dd`), `tipoDocumento`, `buscar`, `pagina` (desde 1), `tamanoPagina` (1 a 100, por defecto 20) | `GET /v1/operaciones` | Lista comprobantes del contribuyente. Continúa con la página siguiente mientras `hayMas` sea `true`. |
| `consultar_operacion` | `idOperacion` (UUID devuelto al emitir) | `GET /v1/operaciones/{idOperacion}` | [Seguimiento](/v1/guias/consulta-operacion) de una emisión, con la misma forma de la respuesta 202: `estado`, `codEstado`, `msgError` (solo si hay error), `errores`, `claveAcceso`, `numeroDocumento`, `fhRecibido` y `fhAutorizacion`, entre otros. |
| `descargar_archivo` | `identificacion`, `claveAcceso` (49 dígitos), `formato` (`ride` o `xml`) | `GET .../comprobantes/{claveAcceso}/ride` o `/xml` | Devuelve el [RIDE](/v1/guias/consulta-ride) (PDF) o el [XML](/v1/guias/consulta-xml) como recurso adjunto. Con otro `formato` responde `Formato invalido: usa ride o xml.` |
| `validar_identificacion` | `numero` (cédula, RUC o pasaporte) | `GET /v1/consultas/identificacion/validar/{numero}` | [Valida el formato](/v1/guias/consulta-identificacion) sin consultar al SRI; revisa `valido`. |
| `consultar_contribuyente` | `identificacion` (cédula, RUC o pasaporte) | `GET /v1/consultas/contribuyentes/{identificacion}` | [Datos del catastro](/v1/guias/consulta-contribuyente) del SRI. |
| `buscar_contribuyentes` | `apellidos` (o inicio de la razón social); opcionales `nombres`, `clase` (`PersonaNatural`, `Sociedad` o `SociedadPublica`), `max` (1 a 30, por defecto 10) | `GET /v1/consultas/contribuyentes` | [Búsqueda en el catastro](/v1/guias/consulta-contribuyente-nombre) por nombre o razón social. |
| `listar_establecimientos` | `ruc` (13 dígitos); opcional `filtro` (`Todos`, `SoloActivos`, `SoloCerrados`, `SoloMatriz` o `SoloSucursales`) | `GET /v1/consultas/establecimientos/{ruc}` | [Establecimientos](/v1/guias/consulta-establecimientos) de un RUC. |
| `decodificar_clave_acceso` | `claveAcceso` (49 dígitos) | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | [Separa la clave](/v1/guias/consulta-clave-acceso) en fecha, tipo, RUC, ambiente, serie y secuencial. |
| `listar_catalogos` | - | `GET /v1/catalogos` | Lista los catálogos del SRI con su clave y una descripción breve. Requiere `sri:consultar`. |
| `obtener_catalogo` | `nombre` (la clave que devuelve `listar_catalogos`, por ejemplo `tarifas-iva`) | `GET /v1/catalogos/{nombre}` | Devuelve las filas de un catálogo con su código y descripción. Con un nombre inexistente responde 404. Requiere `sri:consultar`. |
| `obtener_estado_servicio` | - | `GET /estado` | Estado del servicio, su disponibilidad de los últimos 90 días y los incidentes. Viene con el permiso de ver la cuenta y no consume cupo. |
| `obtener_salud` | - | `GET /salud` | Comprueba que el servicio responde. Viene con el permiso de ver la cuenta y no consume cupo. |

### Documentación

El servidor de tu cuenta trae también las herramientas del
[servidor de documentación](#servidor-de-documentacion), para que el agente
resuelva dudas sobre el API sin que conectes un segundo servidor. Vienen con el
permiso de ver la cuenta, no leen datos de tu cuenta ni consumen cupo, y
responden lo mismo que en el servidor de documentación.

| Herramienta | Parámetros | Para qué sirve |
|---|---|---|
| `listar_guias` | - | Lista las guías agrupadas por tema, con su slug y su URL. |
| `buscar_documentacion` | `consulta`; opcional `maximo` (1 a 20, por defecto 8) | Busca en las guías y devuelve las relevantes con un fragmento. |
| `leer_guia` | `slug` (o la URL de la guía); opcional `seccion` | Devuelve una guía en Markdown, o solo la sección cuyo título coincide. |
| `explicar_error` | `codEstado` (el número de la respuesta, por ejemplo `3002` o `3001`; también acepta su nombre, como `comprobante_invalido`) | Explica un código del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado): `estado`, estado HTTP, cuándo ocurre, qué hacer y si se reintenta. |
| `ejemplo_comprobante` | `tipo` (`01`, `03`, `04`, `05`, `06` o `07`, o su nombre) | Devuelve el JSON del cuerpo de ese tipo, que sirve tal cual como `estructura` de `emitir_comprobante`. |
| `consultar_referencia` | opcionales `ruta` y `metodo` | Consulta el contrato OpenAPI: sin `ruta`, lista los endpoints; con `ruta`, devuelve sus parámetros, cuerpo y respuestas. |

### Escritura

| Herramienta | Parámetros | Endpoint | Para qué sirve |
|---|---|---|---|
| `validar_comprobante` | `identificacion`, `tipo`, `estructura` (JSON del comprobante, como texto) | `POST /v1/contribuyentes/{identificacion}/{ruta}/validar` | [Valida](/v1/guias/emision#validar-sin-emitir) un comprobante con las reglas de la emisión, sin emitirlo ni consumir cupo. Responde `{"valido":true,"errores":[]}` o el error que daría la emisión, por ejemplo 422 con el `codEstado` 3002 (`comprobante_invalido`). Se anuncia como de solo lectura y viene con el permiso de emitir. |
| `emitir_comprobante` | `identificacion`, `tipo`, `estructura` (JSON del comprobante, como texto), `idempotencyKey` (ASCII, máximo 128), `confirmar` (`true`), `validarAntes` (opcional, `false` por defecto) | `POST /v1/contribuyentes/{identificacion}/{ruta}` | Emite un comprobante. Devuelve la respuesta 202 de la API, con `estado` en `recibido`, el `codEstado` 1001 o 1002 y el `idOperacion`; con `validarAntes` en `true` agrega `advertencias` si la validación las devolvió. |

El parámetro obligatorio `tipo` indica qué comprobante envías y solo sirve para elegir la `{ruta}`. Es un valor de la lista de abajo y el servidor MCP lo publica como una enumeración de seis valores en el esquema de la herramienta:

| `tipo` | Comprobante | `{ruta}` |
|---|---|---|
| `factura` | Factura | `facturas` |
| `liquidacion` | Liquidación de compra | `liquidaciones-compra` |
| `nota-credito` | Nota de crédito | `notas-credito` |
| `nota-debito` | Nota de débito | `notas-debito` |
| `guia` | Guía de remisión | `guias-remision` |
| `retencion` | Comprobante de retención | `retenciones` |

La `estructura` es exactamente el cuerpo del esquema de ese tipo y se envía sin cambios: no lleva ningún campo de tipo, y el contrato no incluye `infoTributaria.tipoDocumento` (la API rechaza un cuerpo que lo traiga con el 422 de campo desconocido). La herramienta no completa ni quita campos.

### Perfil y destinos de webhooks

El servidor incluye herramientas para el perfil del emisor y para los destinos de
[webhooks](/v1/guias/webhooks). Cada una exige su propio alcance, que concedes en la
pantalla de permisos al conectar el agente, y aparece en la lista del agente solo si
su token lo trae. Las herramientas que escriben exigen `confirmar` en `true` y no pasan
por la confirmación en el portal, que solo aplica a emitir y enviar correos.
`crear_destino_webhook` y `rotar_secreto_webhook` devuelven el secreto del destino
al agente, así que concede **Gestionar destinos de webhooks** solo a un agente de
confianza.

| Herramienta | Alcance | Parámetros | Endpoint | Para qué sirve |
|---|---|---|---|---|
| `obtener_perfil` | `perfil:leer` | `identificacion` | `GET /v1/contribuyentes/{identificacion}/perfil` | Lee el [perfil del emisor](/v1/guias/perfil-emisor): nombre comercial, dirección matriz, correo, teléfono, ciudad, provincia y logo. |
| `actualizar_perfil` | `perfil:escribir` | `identificacion`, `confirmar`; opcionales `nombreComercial`, `direccionMatriz`, `correo`, `telefono`, `ciudad`, `provincia` | `PUT /v1/contribuyentes/{identificacion}/perfil` | Cambia solo los campos que envías. Se refleja en el RIDE y en los comprobantes siguientes. Requiere al menos un campo. |
| `actualizar_logo_perfil` | `perfil:escribir` | `identificacion`, `logoBase64`, `tipoContenido` (`image/png` o `image/jpeg`), `confirmar` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | Reemplaza el logo del RIDE. PNG o JPEG de hasta 512 KB. |
| `listar_destinos_webhook` | `webhooks:leer` | - | `GET /v1/webhooks/destinos` | Lista los destinos con su estado, RUC y eventos. |
| `obtener_destino_webhook` | `webhooks:leer` | `idDestino` | `GET /v1/webhooks/destinos/{idDestino}` | Configuración y estado de un destino. |
| `listar_entregas_webhook` | `webhooks:leer` | `idDestino` | `GET /v1/webhooks/destinos/{idDestino}/entregas` | Entregas de un destino con su resultado. |
| `listar_intentos_entrega_webhook` | `webhooks:leer` | `idDestino`, `idEntrega` | `GET /v1/webhooks/destinos/{idDestino}/entregas/{idEntrega}/intentos` | Intentos de una entrega, con el código HTTP y el error de cada uno. |
| `crear_destino_webhook` | `webhooks:gestionar` | `url` (HTTPS), `eventos` (separados por coma), `confirmar`; opcional `ruc` | `POST /v1/webhooks/destinos` | Crea un destino. La respuesta trae `secretoUnaVez`, que se muestra una sola vez: el agente debe entregárselo a la persona y no guardarlo en archivos. |
| `actualizar_eventos_webhook` | `webhooks:gestionar` | `idDestino`, `eventos`, `confirmar` | `PUT /v1/webhooks/destinos/{idDestino}/eventos` | Reemplaza la lista completa de eventos. |
| `rotar_secreto_webhook` | `webhooks:gestionar` | `idDestino`, `confirmar` | `POST /v1/webhooks/destinos/{idDestino}/rotar-secreto` | Rota el secreto: el anterior deja de valer y el nuevo llega una sola vez en `secretoUnaVez`. |
| `pausar_destino_webhook` | `webhooks:gestionar` | `idDestino`, `confirmar` | `POST /v1/webhooks/destinos/{idDestino}/pausar` | Pausa las entregas nuevas. |
| `reanudar_destino_webhook` | `webhooks:gestionar` | `idDestino`, `confirmar` | `POST /v1/webhooks/destinos/{idDestino}/reanudar` | Reanuda un destino pausado; solo recibe los eventos desde ese momento. |
| `deshabilitar_destino_webhook` | `webhooks:gestionar` | `idDestino`, `confirmar` | `POST /v1/webhooks/destinos/{idDestino}/deshabilitar` | Da de baja el destino de forma definitiva: para volver a recibir eventos debes crear otro. |
| `probar_destino_webhook` | `webhooks:probar` | `idDestino`, `confirmar` | `POST /v1/webhooks/destinos/{idDestino}/probar` | Envía un evento de prueba, sin comprobante real, a un destino activo. |
| `reintentar_entrega_webhook` | `webhooks:reintentar` | `idDestino`, `idEvento`, `confirmar` | `POST /v1/webhooks/destinos/{idDestino}/entregas/{idEvento}/reintentar` | Vuelve a intentar una entrega fallida o rechazada. |

Los eventos válidos son `document.authorized`, `document.rejected`, `document.failed` y
`operation.requires_attention`. La herramienta `obtener_salud` comprueba que el
servicio responde sin consumir cupo.

## Emisión desde un asistente

La validación con `validar_comprobante` es opcional, porque `emitir_comprobante`
aplica las mismas reglas en la API: el servidor MCP no valida reglas de negocio de
los comprobantes. Conviene cuando el asistente arma los comprobantes a partir de
archivos o de tus indicaciones: así corrige los totales, los impuestos o el RUC
sin emitir nada, y solo te pide confirmación, o tu aprobación en el portal, para
comprobantes que ya pasaron la validación. Para que cada emisión valide antes de
enviar, `emitir_comprobante` acepta el parámetro opcional `validarAntes` (`false`
por defecto): con `true` llama primero a la validación, no emite ni pide
confirmación si el comprobante no cumple, y agrega las `advertencias` al
resultado sin bloquear. Cuesta una petición más por emisión.

Para protegerte de emisiones por error, `emitir_comprobante` aplica tres
controles antes de emitir:

1. `confirmar` debe ser `true`. Si no lo es, la herramienta responde
   `Emision no confirmada: repite con confirmar=true para emitir el comprobante.`
   y no emite. El asistente debe mostrarte el comprobante y pedirte
   confirmación antes de enviar `confirmar=true`.
2. `idempotencyKey` es obligatoria. Pide al asistente que use un valor estable,
   como tu número interno de factura (`FACTURA-2026-0001`), y que lo reutilice
   si reintenta. La misma clave con el mismo cuerpo devuelve la misma operación,
   con el mismo `idOperacion`, en lugar de emitir de nuevo.
3. `estructura` debe ser un objeto JSON válido con la
   [Estructura del comprobante](/v1/guias/emision) del tipo que emites, sin
   ningún campo de tipo: el tipo va en el parámetro `tipo`. Si no es un objeto JSON válido, responde
   `La Estructura del comprobante debe ser un JSON objeto valido.` y no emite.

Cada herramienta declara qué tipo de acción es. Las de lectura se anuncian como
de solo lectura, y `emitir_comprobante` se anuncia como una acción con efecto
fuera de tu cuenta. Los asistentes compatibles, como Claude o ChatGPT, usan esa
marca para pedirte aprobación antes de ejecutar una acción con efecto, aparte
del `confirmar=true` que envía el asistente. No marques esa herramienta como
"permitir siempre": así revisas cada emisión antes de que ocurra.

Las reglas de emisión son las mismas de la API. El `secuencial` es opcional, y
si lo omites, te asignamos el siguiente; el cuerpo no lleva el campo
`claveAcceso`. La respuesta 202 indica que el comprobante quedó **recibido**,
no autorizado, así que el asistente debe consultar después el resultado con
`consultar_operacion` mientras `estado` sea `recibido`. Cualquier otro valor es
final: `autorizado`, o `rechazado`, `rechazo_configuracion`, `error` o
`cancelado`, que llegan con `codEstado`, `msgError` y `errores` para explicar
la causa. Cada tipo de
comprobante tiene su guía: [Factura](/v1/guias/emision-01),
[Liquidación de compra](/v1/guias/emision-03),
[Nota de crédito](/v1/guias/emision-04), [Nota de débito](/v1/guias/emision-05),
[Guía de remisión](/v1/guias/emision-06) y
[Comprobante de retención](/v1/guias/emision-07).

### Confirmación en el portal

Si al conectar el agente dejaste marcada **Pedir mi confirmación para emitir y
enviar correos**, `emitir_comprobante` no se ejecuta en la primera llamada. El
flujo es este:

1. El agente llama a la herramienta con `confirmar=true`. La herramienta no
   emite nada y responde `Pendiente de aprobacion: ...` con un enlace al portal
   del cliente, que vence a los 30 minutos.
2. Abres el enlace con tu usuario del portal. La página muestra el agente, el
   RUC, un resumen (tipo y número del comprobante, contraparte, total y fecha)
   y el detalle completo. Pulsas **Aprobar** o **Rechazar**.
3. Le avisas al agente y él repite la llamada con los mismos datos: la misma
   `idempotencyKey` y la misma `estructura`. Ahora la herramienta se ejecuta.

La aprobación vale solo para ese contenido exacto. Si el agente cambia un dato,
como el total o un ítem, la herramienta pide una aprobación nueva. Después de
aprobar, el agente tiene 30 minutos para repetir la llamada. Una aprobación de
emisión sirve para los reintentos con la misma `idempotencyKey`, que no
duplican el comprobante. Si rechazas, la herramienta responde
`El usuario rechazo ... en el portal` y no se ejecuta.

Pueden aprobar los usuarios de tu cuenta con permiso para emitir con agentes.
Los bots no piden confirmación.

Este es un ejemplo de pedido al asistente en el ambiente de pruebas: "Con
ecuafact, emite una factura de prueba para el contribuyente 0123456789001: un
servicio de 100.00 con IVA 15 %, comprador con cédula 0123456789, pago en
efectivo. Usa la Idempotency-Key FACTURA-2026-0001, muéstrame la estructura
antes de emitir y luego consulta la operación."

> [!WARNING]
> En producción cada emisión autorizada tiene validez fiscal y consume cupo.
> Da el permiso de emitir solo a los agentes que lo necesitan, prueba el flujo
> en pruebas y no apruebes `confirmar=true` sin revisar el comprobante.

## Revocar o editar el acceso

En el portal del cliente, abre **Integración > Agentes IA**. La lista muestra
cada agente conectado, quién lo autorizó, sus permisos, sus RUC, su último uso y
si pide confirmación.

- **Editar permisos** quita permisos a un agente sin desconectarlo; por ejemplo,
  le quita emitir para dejarlo de solo lectura. El cambio aplica desde su
  siguiente llamada. Incluye los permisos de perfil y de webhooks. Solo se pueden
  quitar permisos; para agregar uno, vuelve a conectar el agente. El permiso de ver la cuenta no se puede quitar.
- **Revocar** corta el acceso de un agente en menos de un minuto. Cada persona
  puede revocar los suyos, y un propietario puede revocar los de todos.
- **Revocar bot** desactiva el bot y su `client_secret`.
- Un agente en estado **Sin efecto** quedó suspendido porque quien lo autorizó
  cambió su clave, perdió el permiso o fue desactivado. Para recuperarlo,
  vuelve a conectarlo.

## Errores

Los errores pueden venir del propio servidor MCP, de la API o de la
autorización OAuth. Los del servidor MCP ocurren antes de ejecutar una
herramienta, y tu cliente MCP los muestra como un error de conexión o de
autorización:

| HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|
| 401 | La petición no trae token, el token venció o es de otro ambiente. La respuesta trae `WWW-Authenticate: Bearer` con la dirección de la metadata del servidor. | Los asistentes renuevan o vuelven a pedir la autorización por sí solos, y un bot pide un token nuevo. Si el error persiste, reconecta el agente. |
| 403 | La petición trae una cabecera `Origin` no permitida, algo que ocurre con los clientes que corren en un navegador. | Usa un cliente de escritorio, de terminal o de servidor, porque no envían `Origin`. |
| 413 | El cuerpo pasa de 4 MiB. | Reduce la `estructura`; la API acepta hasta 2 MiB por comprobante. |
| 415 | Llegó un `POST` sin `Content-Type: application/json`. | Actualiza tu cliente MCP; los clientes compatibles envían la cabecera por sí solos. |
| 429 | Un mismo agente hizo más de 120 llamadas por minuto, o una misma IP hizo más de 600 peticiones por minuto sin token válido. La respuesta trae `Retry-After`. | Espera el tiempo que indica `Retry-After` y reduce el ritmo. |

Cuando el error ocurre al ejecutar una herramienta, el asistente recibe el
texto `An error occurred invoking '<herramienta>': <mensaje>`:

| Mensaje o código | Cuándo ocurre | Qué hacer |
|---|---|---|
| `El acceso de este agente fue revocado o ya no es valido. Vuelve a conectar el agente desde Agentes IA del portal.` | Revocaste el agente, quien lo autorizó cambió su clave o perdió el permiso, o el bot fue revocado. | Vuelve a conectar el agente (o crea otro bot). |
| `No se pudo validar el acceso del agente. Intenta de nuevo en unos segundos.` | Hubo una falla transitoria al validar el acceso. | Reintenta en unos segundos. |
| `El API respondio 403 [codEstado 3011 acceso_denegado]: <msgError>` | El RUC no está entre los que autorizaste para este agente, o el tipo de comprobante no está habilitado. | Revisa `obtener_contexto`; si el RUC falta, reconecta el agente incluyéndolo. |
| `El API respondio <HTTP> [codEstado <número> <nombre>]: <msgError> Errores: <error>; <error>` (otros) | La API rechazó la petición con su error estable. El texto trae el `codEstado` con su nombre, el `msgError`, en 3002 hasta 20 `errores` separados por punto y coma y, en algunos códigos, una indicación de qué hacer. | Actúa según el `codEstado`, como indica la tabla siguiente. |
| `El API no esta disponible (<HTTP>). Reintenta en unos minutos.` | La API no respondió con su error estable, por ejemplo durante un mantenimiento. | Reintenta en unos minutos. Al emitir, usa la misma `idempotencyKey`. |
| `El API respondio <HTTP> sin detalle.` | La API rechazó la petición sin su error estable. | Revisa los parámetros de la llamada y reintenta. |
| `El usuario rechazo emitir este comprobante en el portal. ...` | Rechazaste la [confirmación](#confirmacion-en-el-portal) en el portal. | Dile al agente qué cambiar. Con datos distintos, la herramienta pide una aprobación nueva. |
| `La documentacion no esta disponible ...` o `La documentacion recibio demasiadas consultas. Reintenta en un minuto.` | Una herramienta de [documentación](#documentacion) no pudo consultar el servidor de documentación. | Reintenta en un minuto. |

Los textos que devuelven las herramientas, como la razón social o los mensajes
de error, se recortan a 1000 caracteres (a 300 en los mensajes de error).

Una respuesta JSON admite hasta 100 elementos por arreglo y 64 KiB en total. Si supera
ese límite, la herramienta pide reducir el período o el tamaño de página; no devuelve una
lista parcial sin indicarlo. `descargar_archivo` admite adjuntos de hasta 1 MiB. Para archivos
mayores usa la descarga del SDK, del CLI o de la API.

Los permisos de perfil y de webhooks que no concediste dejan las herramientas
correspondientes fuera de la lista del agente, como se explica en
[Perfil y destinos de webhooks](#perfil-y-destinos-de-webhooks).

Estos son los códigos de la API más comunes cuando trabajas desde un asistente:

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 3011 (`acceso_denegado`) | 403 | El RUC no está autorizado para el agente, el contribuyente o el tipo de comprobante no está habilitado. | Revisa `obtener_contexto` y usa su `identificacion` en la herramienta y en `infoTributaria.ruc`. |
| 5005 (`limite_solicitudes`) | 429 | Superaste las solicitudes por minuto de tu integración. Las llamadas del MCP cuentan igual que las de tu sistema. | Espera a que termine el minuto en curso y reintenta. |
| 3003 (`solicitud_invalida`) | 400 | La `idempotencyKey` no es válida, el JSON está mal formado o un parámetro tiene un formato inválido. | Revisa la `idempotencyKey`, que debe ser ASCII de hasta 128 caracteres, y el JSON de `estructura`. |
| 3002 (`comprobante_invalido`) | 422 | Faltan campos del comprobante o están mal formados, o se incumple una regla fiscal. | Corrige `estructura` según `errores`. Este error consume 1 documento como intento. |
| 3004 (`comprobante_duplicado`) | 409 | Ya existe un comprobante con ese número (`estab`, `ptoEmi`, `secuencial`). | No lo reenvíes. Usa el `idOperacion` de la emisión original u omite `secuencial`. |
| 3005 (`conflicto_idempotencia`) | 409 | Se usó la misma `idempotencyKey` con otro contenido. | Reenvía el contenido original o usa una clave nueva para otro comprobante. |
| 4004 (`cupo_agotado`) | 429 | Se agotó el cupo. | Revisa `obtener_consumo`; esperar no repone el cupo. |
| 3013 (`no_encontrado`) | 404 | El `idOperacion` o la clave de acceso no existen, o el comprobante aún no está autorizado. | Revisa el identificador. Descarga el RIDE o el XML cuando el comprobante esté autorizado. |

Por último, estos son los errores de autorización que pueden aparecer al pedir
un token para un bot o al conectar un asistente:

| Error OAuth | Cuándo ocurre | Qué hacer |
|---|---|---|
| `invalid_client` | El `client_id` o el `client_secret` son incorrectos, o el bot fue revocado. | Revisa las variables `ECUAFACT_BOT_ID` y `ECUAFACT_BOT_SECRET`; si el bot se revocó, crea otro. |
| `invalid_scope` | Pediste un permiso que el bot no tiene. | Pide solo los permisos del bot o crea otro bot con ese permiso. |
| `access_denied` | Cancelaste la autorización, o tu rol no permite autorizar agentes. | Pide a un propietario el permiso **Autorizar agentes IA (consulta)** y vuelve a conectar. |
| `invalid_grant` | El acceso del agente se revocó o su autorización venció. | Vuelve a conectar el agente. |

El catálogo completo de códigos de la API está en [Errores](/v1/guias/errores).

## Skill

Puedes complementar el MCP con nuestro
[skill para asistentes](/v1/guias/skill), que le enseña a tu asistente a
construir comprobantes correctos, con los campos, los códigos del SRI y las
reglas de cálculo. Con el skill, el asistente sabe qué enviar, y con el MCP lo
envía por ti.

## Siguientes pasos

- [Skill para asistentes de IA](/v1/guias/skill): instala el conocimiento de la API en tu asistente.
- [Instrucciones para agentes](/v1/guias/agentes): revisa el resumen del contrato y las reglas que debe seguir un agente.
- [Factura](/v1/guias/emision-01): conoce la estructura que el asistente envía en `estructura`.
