Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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:

Prompt para agentes

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#

  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:

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:

  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.
  3. 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#

  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.

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:

  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 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, 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:

  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."

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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

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

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

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

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

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