En esta página
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:
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 que le des.
- Sobre qué RUC. Puede trabajar con todos los contribuyentes 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 |
| 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 |
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.
Importante
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 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, 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. |
Para conectarlo en Claude Code:
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.
- 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#
- Abre Configuración > Conectores > Agregar conector personalizado.
- Escribe un nombre (por ejemplo,
Ecuafact) y la URLhttps://mcp-sandbox.mynexusapi.com/mcp. - Pulsa Conectar y se abrirá el portal del cliente. Inicia sesión, elige los permisos y los RUC y pulsa Permitir.
ChatGPT#
- Activa el modo desarrollador en Configuración > Aplicaciones y conectores > Configuración avanzada.
- En Aplicaciones y conectores, pulsa Crear, escribe la URL
https://mcp-sandbox.mynexusapi.com/mcpy elige OAuth como autenticación. - Autoriza en el portal del cliente como en el paso 3 de Claude.
Claude Code#
Registra el servidor y autorízalo desde Claude Code:
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.
{
"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.
{
"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.
{
"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:
{
"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:
- Pide al asistente: "Usa la herramienta obtener_contexto de ecuafact".
- Comprueba que responde con tu integración y solo con los RUC que autorizaste. Es el mismo JSON que devuelve Contexto.
- Si ves un error, búscalo en 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#
- 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.
- Escribe un nombre, elige los permisos y los RUC y pulsa Crear.
- Guarda el
client_idy elclient_secretque aparecen, porque el secreto no se vuelve a mostrar.
Atención
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.
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:
{
"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:
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
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:
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:
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:
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
$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 |
| 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. 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.
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.
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 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 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 (PDF) o el 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 sin consultar al SRI; revisa valido. |
consultar_contribuyente |
identificacion (cédula, RUC o pasaporte) |
GET /v1/consultas/contribuyentes/{identificacion} |
Datos del catastro 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 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 de un RUC. |
decodificar_clave_acceso |
claveAcceso (49 dígitos) |
GET /v1/consultas/comprobantes/decodificar/{claveAcceso} |
Separa la clave 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, 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: 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 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. 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: 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:
confirmardebe sertrue. Si no lo es, la herramienta respondeEmision 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 enviarconfirmar=true.idempotencyKeyes 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 mismoidOperacion, en lugar de emitir de nuevo.estructuradebe ser un objeto JSON válido con la Estructura del comprobante del tipo que emites, sin ningún campo de tipo: el tipo va en el parámetrotipo. Si no es un objeto JSON válido, respondeLa 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,
Liquidación de compra,
Nota de crédito, Nota de débito,
Guía de remisión y
Comprobante de retención.
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:
- El agente llama a la herramienta con
confirmar=true. La herramienta no emite nada y respondePendiente de aprobacion: ...con un enlace al portal del cliente, que vence a los 30 minutos. - 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.
- Le avisas al agente y él repite la llamada con los mismos datos: la misma
idempotencyKeyy la mismaestructura. 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."
Atención
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 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 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.
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.
Skill#
Puedes complementar el MCP con nuestro skill para asistentes, 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: instala el conocimiento de la API en tu asistente.
- Instrucciones para agentes: revisa el resumen del contrato y las reglas que debe seguir un agente.
- Factura: conoce la estructura que el asistente envía en
estructura.