Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Changelog

Cambios de la API, los SDK, el CLI y el servidor MCP que afectan tu integración, por versión y con fecha.

Cada versión se registra aquí con su fecha. Cuando un cambio exija una acción de tu parte, la entrada explica qué cambió, qué impacto tiene y qué debes hacer; un cambio incompatible se marca como incompatible y trae su guía de migración.

Cambios del 20 de noviembre de 2026#

Consumo de cupo en las guías y colección de Postman#

  • Qué cambió. Las guías de emisión, primeros pasos, ciclo de vida, errores y preguntas frecuentes indican ahora, de forma uniforme, que un 422 por formato o validación del comprobante (comprobante_invalido) consume 1 documento como intento, siempre que el RUC esté autorizado para tu API Key; repetir la misma Idempotency-Key con el mismo cuerpo no consume otro, y una solicitud mal formada (400) no consume. La descripción de la colección de Postman usa la URL de pruebas api-sandbox, indica que la IP registrada se exige solo en producción y remite a Cuenta > API Keys para obtener la clave.
  • Impacto. Ninguno en el comportamiento de la API, los SDK, el CLI ni el servidor MCP. Si estimabas tu cupo con la versión anterior de esas guías, ajusta la estimación: cada intento rechazado por validación cuenta.
  • Qué hacer. Valida antes de emitir con la ruta /validar de cada tipo, que no consume cupo, y vuelve a importar la colección de Postman si quieres la descripción actualizada.

Cambios del 19 de noviembre de 2026#

Espera y correos al agregar un RUC en pruebas#

  • Qué cambió. Al agregar un RUC en el Portal del Cliente, la configuración de su ambiente de pruebas empieza de inmediato y el portal muestra el mensaje "Espera un momento..." hasta que termina. Si pasa un minuto sin terminar, el mensaje se cierra y te avisa que recibirás un correo. Recibes un correo al agregar el RUC y otro cuando el ambiente queda listo. La modalidad del RUC llega preseleccionada en Normal y el formulario ya no autocompleta sus campos.
  • Impacto. Ninguno en la API, los SDK, el CLI ni el servidor MCP.
  • Qué hacer. Nada. Espera el mensaje o el correo antes de emitir con el RUC nuevo.

Bienvenida y primera API Key de pruebas#

  • Qué cambió. La primera vez que entras al Portal del Cliente con tu sandbox, un mensaje de bienvenida te ofrece generar tu API Key de pruebas. Si eliges Ahora no o lo cierras, no vuelve a aparecer: mientras no tengas clave, Pruebas muestra el botón Generar en la tarjeta "API Key de pruebas".
  • Impacto. Ninguno en la API, los SDK, el CLI ni el servidor MCP. Las cuentas que ya existen no ven el mensaje.
  • Qué hacer. Nada. Genera tu clave desde el mensaje o desde Pruebas y guárdala en ECUAFACT_API_KEY.

Cambios del 18 de noviembre de 2026#

La serie del comprobante se envía en cada emisión#

  • Qué cambió. El Portal del Cliente ya no tiene la pantalla Configurar series. El establecimiento y el punto de emisión se envían en cada comprobante y el secuencial se omite para que la API asigne el siguiente, como se explica en Secuencial automático. El alta crea la serie 001-001, y en Pruebas > Emitir prueba el número se escribe en el formulario.
  • Impacto. El contrato no cambia: infoTributaria.estab, ptoEmi y secuencial conservan su forma. Quien administraba varias series desde el portal ahora envía esos valores en la solicitud.
  • Qué hacer. Envía estab y ptoEmi en cada documento; si omites secuencial, la API asigna el siguiente. No hay cambios en los SDK, el CLI ni el servidor MCP.

Búsqueda por el número completo del comprobante#

  • Qué cambió. El filtro de búsqueda de GET /v1/operaciones, y su total, coincide también con el número completo del comprobante, por ejemplo 001-001-000000123, además del secuencial, la clave de acceso y la contraparte.
  • Impacto. Ninguno: es una coincidencia adicional del mismo filtro y el paginado no cambia.
  • Qué hacer. Nada.

Bienvenida al pasar a producción#

  • Qué cambió. El primer paso a producción ya no exige comprar un paquete. Se habilita con correo verificado, firma vigente y, en autoservicio, al menos 5 comprobantes de prueba aceptados. Al confirmar, la cuenta recibe 20 documentos de producción con vigencia de un año. Cuando se agoten, puedes comprar un paquete en Consumo.
  • Impacto. No cambia el contrato de la API ni el paquete de pruebas de 3.000 documentos. El saldo de producción inicial es de 20 documentos.
  • Qué hacer. Ninguna acción en las integraciones. Si el cliente pasa por el portal, no necesita registrar un pago previo.

Cupones en la compra de paquetes#

  • Qué cambió. En el pago de un paquete puedes escribir un código de cupón y ver el descuento antes de pagar. El descuento se aplica sobre el subtotal, antes del IVA, y el total lo calcula el servidor. Si el cupón no aplica, el portal indica el motivo.
  • Impacto. No cambia el contrato de la API. El cupón solo aplica a la compra de paquetes y cada cuenta puede usarlo una vez.
  • Qué hacer. Ninguna acción en las integraciones. Los cupones se solicitan a comercial.

Compra de paquetes en el Portal del Cliente#

  • Qué cambió. En Uso y paquetes > Comprar paquetes eliges la cantidad de comprobantes en una barra con paradas fijas, de 100 a 30.000. El precio se muestra sin IVA y el IVA (15 %) se suma en el pago. Puedes pagar con transferencia, tarjeta o deUna. El paquete queda vigente un año desde el pago.
  • Impacto. No cambia el contrato de la API ni el consumo de documentos. La compra de paquetes deja de ser una demostración.
  • Qué hacer. Ninguna acción en las integraciones. Para más de 30.000 comprobantes, usa los canales de comercial que aparecen en la pantalla.

Portal del Cliente: API Keys y búsqueda de comprobantes#

  • Qué cambió. La sección Cuenta > Acceso del Portal del Cliente se llama Cuenta > API Keys. Mientras tu cuenta está en pruebas, la API Key de pruebas se obtiene en Pruebas con Rotar; las API Keys de producción se crean en API Keys con Crear API Key. El filtro buscar del listado de comprobantes emitidos también coincide con el número completo establecimiento-puntoEmision-secuencial, por ejemplo 001-001-000000123. Los mensajes de validación de ese listado llevan tildes.
  • Impacto. Ninguno en el contrato de la API, los SDK, el CLI ni el servidor MCP.
  • Qué hacer. Usa los nombres nuevos al seguir las guías. Si tienes capturas o instrucciones internas que mencionan Acceso, actualízalas.

Cambios del 17 de noviembre de 2026#

Alta de la cuenta: celular, correo y clave#

  • Qué cambió. El alta en https://portal.mynexusapi.com/sandbox sigue este orden: completas tus datos, confirmas tu celular con un código de 6 dígitos que llega por WhatsApp y creas tu clave con el enlace del correo "Crea tu clave de Ecuafact". La cuenta se crea cuando creas la clave. El código vence en 10 minutos, admite 5 intentos y se puede reenviar pasados 60 segundos. El enlace del correo se usa una sola vez y se puede abrir desde cualquier equipo; tienes 7 días desde que confirmas el celular para crear la clave. Un mismo celular admite hasta 3 cuentas y, en 24 horas, hasta 5 códigos y 5 correos del alta. Si vuelves al formulario con Cambiar número o Corregir correo, confirmas el celular otra vez con un código nuevo. Los nombres y apellidos admiten de 2 a 100 caracteres, solo con letras, espacios, apóstrofo, guion y punto, y la clave admite de 8 a 128 caracteres. Recibes un solo correo durante el alta, y la API Key de pruebas ya no se muestra al terminar: la obtienes en Pruebas del Portal del Cliente.
  • Impacto. Las cuentas existentes no cambian. Un alta que quedó a medias con el orden anterior vuelve al paso del código. Si pasan 24 horas sin que avances en el alta antes de confirmar el celular, o 7 días desde que lo confirmaste sin crear la clave, los datos del alta se eliminan y empiezas de nuevo. Si tu correo ya tiene una cuenta, recibes el correo "Ya tienes una cuenta de Ecuafact" para ingresar con tu clave.
  • Qué hacer. Ten el celular a mano al enviar el formulario y revisa el correo antes de continuar, porque corregirlo después pide otro código. Después de crear la clave, ingresa al portal, abre Pruebas, pulsa Rotar y copia la API Key de pruebas, que se muestra una sola vez. El paso a paso está en Sandbox de pruebas. No hay cambios en la API, los SDK, el CLI ni el servidor MCP.

Alta del sandbox y MCP de pruebas#

  • Qué cambió. El alta en https://portal.mynexusapi.com/sandbox pide nombres y apellidos por separado, un celular con WhatsApp de Ecuador y la aceptación de los Términos y Condiciones y la Política de Protección de Datos Personales. La casilla de comunicaciones comerciales es opcional. El portal de pruebas https://staging-portal.mynexusapi.com deja de existir: el alta y la gestión del sandbox se hacen en el portal de producción. El MCP de pruebas (https://mcp-sandbox.mynexusapi.com/mcp) sigue disponible, pero su autorización se hace en https://portal.mynexusapi.com y solo mientras la cuenta está en estado sandbox. Al pasar a producción, esa conexión se revoca.
  • Impacto. Las cuentas existentes no cambian. Las altas nuevas necesitan teléfono y consentimiento. Un agente conectado a mcp-sandbox debe volver a autorizarse en el portal de producción; si la cuenta ya pasó a producción, usa el MCP de producción (https://mcp.mynexusapi.com/mcp).
  • Qué hacer. Si tienes enlaces al portal de pruebas, cámbialos a https://portal.mynexusapi.com. Para el MCP de pruebas, reconecta el agente desde el portal de producción mientras la cuenta siga en sandbox. No hay cambios en la API, los SDK ni el CLI.

Cambios del 16 de noviembre de 2026#

Esta entrada reúne los cambios de contrato posteriores a la versión 1.0.0. Ninguno es incompatible con una integración que ya emite correctamente, pero cambian el cobro de documentos, la lista de IP y la clave que calcula el CLI.

Nuevas direcciones de pruebas y de la documentación#

  • Qué cambió. La API de pruebas es https://api-sandbox.mynexusapi.com, el servidor MCP de pruebas es https://mcp-sandbox.mynexusapi.com/mcp y la documentación está en https://docs.mynexusapi.com. Producción no cambia: https://api.mynexusapi.com, https://mcp.mynexusapi.com/mcp y https://portal.mynexusapi.com. Los SDK y el CLI 1.0.1 usan las direcciones nuevas, y los SDK 1.0.1 agregan a InfoTributaria los campos opcionales razonSocial, nombreComercial y dirMatriz.
  • Impacto. https://staging-api.mynexusapi.com sigue respondiendo con el mismo contrato. Las páginas de https://docsapi.ecuafact.com redirigen con HTTP 301 a la misma ruta en https://docs.mynexusapi.com; su servidor MCP de documentación sigue respondiendo en la dirección anterior. Un agente conectado a https://mcp-staging.mynexusapi.com/mcp debe volver a conectarse con la dirección nueva, porque la autorización OAuth se emite para https://mcp-sandbox.mynexusapi.com/mcp.
  • Qué hacer. Cambia la URL base de pruebas en tu configuración a https://api-sandbox.mynexusapi.com, actualiza los SDK y el CLI a 1.0.1 y reconecta tus agentes de pruebas a https://mcp-sandbox.mynexusapi.com/mcp. Actualiza tus enlaces a la documentación.

Portal y datos del emisor por documento#

  • Qué cambió. El registro pide nombre y correo; después de confirmarlo defines tu contraseña. Agregas los RUC dentro de la cuenta y administras sus certificados por separado. Contribuyentes permite consultar los datos de referencia y editarlos manualmente. Comprobantes reúne documentos y operaciones; sin RUC seleccionado consulta todos los autorizados de tu cuenta. Acceso reúne claves y la restricción opcional de IP. Uso y paquetes muestra saldo y movimientos; Facturación muestra compras. La compra de paquetes de documentos se cobra con transferencia, tarjeta o deUna; la compra de planes y de certificados no está disponible en el portal.
  • Emisión. JSON admite infoTributaria.razonSocial, nombreComercial y dirMatriz (hasta 300 caracteres). En XML se toman esos elementos del documento. estab y ptoEmi siguen llegando en cada solicitud. Si omites los campos nuevos se conserva el perfil previamente configurado.
  • Impacto. Las altas nuevas agregan sus RUC después del registro. La validación 422 conserva su resultado al repetir cuerpo y clave; cambiar el cuerpo con esa clave responde 409. Los certificados que necesitan acreditar representación quedan en revisión; una renovación pendiente conserva la firma activa.
  • Reenvíos. La misma clave y el mismo cuerpo devuelven HTTP 202 con la operación y su estado actual, incluso cuando ya terminó. Una corrección de contenido tras un rechazo terminal permite conservar la referencia y el número, con una nueva Idempotency-Key; consume un documento. No reenvíes una operación pendiente ni autorizada.
  • Qué hacer. Conserva tus claves y referencias actuales. Para nuevas integraciones envía los datos fiscales en el documento. La API pública sigue exigiendo un RUC en su listado de operaciones y las URLs de pruebas y producción permanecen separadas.

Paquetes de documentos#

  • Qué cambió. Tu saldo de documentos sale de paquetes. Cada paquete es de un ambiente, tiene una cantidad de documentos y una vigencia; los de producción duran un año desde el pago y los de pruebas no vencen. Al emitir se descuenta del paquete vigente que vence primero. Ya no hay plan mensual: GET /v1/consumo informa la suma de tus paquetes vigentes (límite, en proceso, consumido y disponible) y en vigencia la fecha del próximo paquete que vence. Pasar a producción pide un paquete de producción con saldo en lugar de una suscripción.
  • Impacto. Sin un paquete vigente con saldo, la emisión responde 429 con el codEstado 4004 (cupo_agotado); ya no existe el 403 por plan vencido.
  • Qué hacer. Si tu integración leía la vigencia del plan en GET /v1/consumo, léela como el vencimiento del próximo paquete. Compra o renueva paquetes desde Consumo en el Portal del Cliente.

Qué consume un documento#

  • Qué cambió. Cada comprobante que envías consume 1 documento, lo autorice o no el SRI. Un envío rechazado con 422 por formato o validación también consume 1 como intento. No consumen: repetir la misma Idempotency-Key con el mismo cuerpo (también si la primera respuesta fue un 422), reenviar un comprobante rechazado sin cambios aunque hayas cambiado la firma electrónica o la modalidad del contribuyente, la validación con /validar, un RUC que no está habilitado en tu integración y un contribuyente sin firma electrónica configurada. Reenviar un comprobante rechazado con cambios en su contenido consume 1.
  • Impacto. Un ERP que reintenta un comprobante inválido con una Idempotency-Key nueva en cada intento consume un documento por intento.
  • Qué hacer. Valida con /validar antes de emitir y reintenta con la misma Idempotency-Key.

Referencia externa por RUC#

  • Qué cambió. referenciaExterna es única por contribuyente emisor, no por integración: dos RUC de tu integración pueden usar la misma referencia. El mismo RUC sigue sin poder repetirla.
  • Impacto. Ninguno para una integración que ya usa referencias únicas.
  • Qué hacer. Nada.

Lista de IP permitidas#

  • Qué cambió. Cuenta > API Keys permite activar o desactivar la restricción por IP. Acepta rangos IPv6 en notación CIDR, con prefijo de /32 o más largo, y rechaza 0.0.0.0/0 y ::/0. Para desactivarla, todas tus claves activas deben estar limitadas a servicios y RUC concretos. Mientras está activa necesitas al menos una IP permitida.
  • Impacto. Una lista que contenía 0.0.0.0/0 ya no se puede guardar.
  • Qué hacer. Registra tus IP o rangos reales, o usa una API Key limitada a los servicios y RUC que necesitas.

Correos en pruebas#

  • Qué cambió. En el ambiente de pruebas, el correo del comprobante se envía solo al correo del titular de tu cuenta, sea cual sea el comprador.
  • Impacto. Tus clientes no reciben correos de comprobantes de prueba.
  • Qué hacer. Nada.

CLI y SDK#

  • Qué cambió. El CLI ecuafact calcula la Idempotency-Key con el RUC emisor, el tipo de comprobante, origenReferencia y referenciaExterna. El SDK de Node.js no sigue redirecciones HTTP automáticamente. La guía del servidor MCP ya no pide tipoDocumento en el ejemplo de emisión: la herramienta lo toma del tipo elegido.
  • Impacto. Un comprobante emitido con una versión anterior del CLI y reenviado con la nueva lleva otra Idempotency-Key; la API lo reconoce por su referencia y no emite otro comprobante.
  • Qué hacer. Actualiza el CLI.

Ecuafact API 1.0.0 - 16 de noviembre de 2026#

Ecuafact API 1.0.0 es la primera versión de la plataforma. Con ella puedes emitir y consultar los seis comprobantes electrónicos del SRI, administrar tu cuenta y recibir los resultados por webhook, y puedes integrarte con la API directamente, con los SDK oficiales, con el CLI ecuafact o con el servidor MCP para agentes de IA. Esta entrada describe todo lo que ofrece y los límites que aplican hoy.

Emisión de comprobantes#

Puedes emitir los seis comprobantes del SRI: factura (01), liquidación de compra (03), nota de crédito (04), nota de débito (05), guía de remisión (06) y comprobante de retención (07). Cada tipo tiene su propia ruta, que fija el tipo de comprobante, y todos comparten la misma estructura de cuerpo y las mismas cabeceras. La emisión acepta el comprobante en JSON o en el XML del SRI, firmado o sin firmar; en el segundo caso la plataforma vuelve a firmarlo. La retención en XML debe usar la versión 2.0 con docsSustento.

La emisión es asíncrona. La API valida el comprobante y responde 202 Accepted con un idOperacion, una urlEstado y el estado recibido; el resultado del SRI llega después, y lo conoces consultando la operación o recibiendo un webhook. Si la autorización o un rechazo definitivo ya se conocen al responder, la respuesta lo indica en el mismo cuerpo. Cada emisión exige la cabecera Idempotency-Key, de 1 a 128 caracteres: repetir la misma clave con el mismo cuerpo devuelve la misma operación sin emitir otro comprobante, y repetirla con un cuerpo distinto responde 409. Si omites el secuencial o lo envías en ceros, la plataforma asigna el siguiente de la serie.

Puedes comprobar un comprobante sin emitirlo con la ruta de su tipo seguida de /validar. La validación no consume cupo, no exige Idempotency-Key y devuelve todos los problemas encontrados, cada uno con la ruta del campo. Los límites vigentes son 2 MiB por cuerpo de emisión, 32 niveles de anidamiento, de 1 a 1000 líneas de detalle, hasta 20 pagos en factura y liquidación de compra y hasta 15 campos en infoAdicional. Un comprobante autorizado no se edita: se corrige con una nota de crédito.

Guías: Comprobantes electrónicos, Factura, Liquidación de compra, Nota de crédito, Nota de débito, Guía de remisión, Comprobante de retención, Ciclo de vida del comprobante y Catálogos.

Consulta de operaciones y descarga de archivos#

Con GET /v1/operaciones/{idOperacion} sigues una emisión hasta su resultado. La respuesta tiene la misma forma que el 202 de la emisión e incluye el estado, el codEstado, la claveAcceso de 49 dígitos, el numeroDocumento y las fechas de recepción y autorización. Los estados son recibido, autorizado, rechazado, rechazo_configuracion, error y cancelado, y solo autorizado tiene validez fiscal. Para reconciliar un período, GET /v1/operaciones lista los comprobantes de un contribuyente con paginación. Acepta un rango de fechas de hasta 366 días (30 días si no lo indicas), el filtro por tipo de comprobante, una búsqueda de texto de hasta 100 caracteres y páginas de 1 a 100 elementos.

Con la clave de acceso descargas el RIDE, el PDF del comprobante, y el XML autorizado cuando el comprobante ya está autorizado; solo el RIDE y el XML de un comprobante autorizado tienen validez fiscal. Un contribuyente de marca blanca emite y recibe la autorización como cualquier otro, pero no tiene RIDE; su campo marcaBlanca en el contexto te lo indica.

Guías: Seguimiento de una operación, Descargar PDF y Descargar XML.

Contribuyentes y consultas al SRI#

GET /v1/contexto devuelve tu integración y los contribuyentes habilitados, con la identificacion que usas en las rutas y en infoTributaria.ruc, los tipos de comprobante que puedes emitir y si cada contribuyente es de marca blanca. Con GET y PUT sobre el perfil del emisor lees y actualizas los datos que salen en el RIDE (nombre comercial, dirección de la matriz, correo, teléfono, ciudad y provincia), y con POST sobre el logo subes una imagen PNG o JPEG de hasta 512 KB.

Además puedes consultar el catastro del SRI desde la misma API Key: un contribuyente por cédula, RUC o pasaporte; contribuyentes por apellidos y nombres o por el inicio de la razón social (de 1 a 30 resultados); los establecimientos de un RUC, con filtros por estado y por matriz o sucursales; la validación del formato y el dígito verificador de una identificación, y la decodificación de una clave de acceso en sus partes. Estas consultas no consumen cupo, pero sí cuentan para el límite de solicitudes por minuto.

Los catálogos del SRI que usa la Estructura del comprobante (tipos de comprobante y de identificación, impuestos, tarifas de IVA, formas de pago, retenciones de IVA e ISD, ambientes, tipos de emisión y restricciones de campos) los lees con GET /v1/catalogos, que lista las claves, y GET /v1/catalogos/{nombre}, que devuelve las filas con su código, descripción, valor y vigencia. La respuesta puede guardarse hasta una hora.

Guías: Contexto, Catálogos, Perfil del emisor, Contribuyente por identificación, Contribuyentes por nombre, Establecimientos de un RUC, Validar identificación y Decodificar clave de acceso.

Cuenta, acceso y ambientes#

La API tiene un ambiente de pruebas, sin validez fiscal, y uno de producción, con validez fiscal. Los dos comparten el mismo contrato y solo cambian la URL base y la API Key: https://staging-api.mynexusapi.com para pruebas y https://api.mynexusapi.com para producción. Toda llamada a /v1 lleva la API Key en la cabecera X-Api-Key, y una sola API Key cubre todos los contribuyentes habilitados de tu integración. Cada API Key se limita por servicios (scopes) y por RUC, se crea y se revoca desde la sección Cuenta > API Keys del Portal del Cliente, y se muestra completa una sola vez. En producción, la API solo acepta las IP que registraste en Cuenta > IP permitidas, ya sea como dirección IPv4 o IPv6 exacta o como rango IPv4 en notación CIDR; el sandbox acepta cualquier IP.

Puedes crear tu sandbox por autoservicio en https://portal.mynexusapi.com/sandbox, sin contrato. Recibes una API Key de pruebas, un cupo único de 3.000 documentos sin renovación automática y un límite de 60 solicitudes por minuto. Cuando estés listo, Pasar a producción se habilita con el correo verificado, una firma electrónica vigente, al menos 5 comprobantes de prueba aceptados y una suscripción de producción activa. El paso a producción no se puede deshacer. En Contribuyentes agregas tus RUC con su certificado de firma electrónica (.p12 o .pfx); el establecimiento y el punto de emisión viajan en cada comprobante (infoTributaria.estab y ptoEmi), y el alta crea la serie 001-001.

GET /v1/consumo informa tu cupo de documentos, que suma el plan y los paquetes: el límite contratado, lo que está en proceso, lo consumido, lo disponible y la vigencia del plan. Con el cupo agotado, la emisión responde 429 con el codEstado 4004 (cupo_agotado); con el plan vencido, responde 403 con el 3011 (acceso_denegado).

Los límites de uso son 200 solicitudes por minuto por integración (60 en un sandbox) y 20 intentos de autenticación fallidos por minuto por IP y por identificador de API Key. Al superarlos, la API responde 429 con el codEstado 5005 (limite_solicitudes), la cabecera Retry-After con los segundos que debes esperar y las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining. Los demás topes son 1 MiB por cuerpo en los POST y PUT que no son de emisión, 32 niveles de anidamiento JSON y un X-Additional-Info opcional de hasta 256 caracteres para identificar tus solicitudes ante soporte. Conservamos tus comprobantes durante siete años y puedes pedir una exportación masiva a soporte.

Guías: Autenticación, Ambientes y contribuyentes, Sandbox de pruebas, Datos de prueba, Consumo y cuotas, Límite de request, Límites y Continuidad y salida.

Webhooks#

Puedes recibir el resultado de cada emisión en un endpoint HTTPS tuyo, sin consultar el seguimiento. Los eventos son document.authorized, document.rejected, document.failed y operation.requires_attention, este último un aviso de que un comprobante sigue recibido sin resultado confirmado. Cada destino recibe los eventos de todos tus RUC o solo los de uno, y se administra desde Integración > Eventos del Portal del Cliente, con el CLI (ecuafact webhooks), con el servidor MCP (permisos webhooks:leer, webhooks:gestionar, webhooks:probar y webhooks:reintentar) o con la API REST. Puedes crear, listar, cambiar los eventos, rotar el secreto, probar, pausar, reanudar, deshabilitar, revisar las entregas y sus intentos, y reenviar un evento.

Los SDK verifican la firma de los webhooks que recibes. Cada entrega va firmada con Ecuafact-Signature y con las cabeceras del estándar Standard Webhooks, y el secreto del destino se muestra una sola vez. Tu servidor debe responder un 2xx en menos de 15 segundos. Si no responde a tiempo, no se puede conectar o responde 408, 429 o 5xx, la entrega se reintenta con esperas crecientes; cualquier otro 4xx o un 3xx deja la entrega rechazada sin reintentos. La guía de webhooks detalla los intentos. Te recomendamos conservar el seguimiento como respaldo.

Guías: Webhooks y Verificación de firma.

Errores y respuestas#

Toda respuesta de error tiene el mismo cuerpo plano, con estado, codEstado, msgError y errores. El codEstado es un número estable de cuatro dígitos cuyo primer dígito coincide con el estado: 1 es recibido, 2 autorizado, 3 rechazado, 4 rechazo_configuracion, 5 error y 6 cancelado. El mismo código aparece en la emisión, en el seguimiento y en los webhooks, por lo que un solo catálogo te sirve para decidir si debes esperar, reintentar o corregir. Un 429 puede significar límite de solicitudes (5005, se resuelve esperando) o cupo agotado (4004, no se resuelve esperando), así que decide siempre con el codEstado.

Todas las respuestas traen X-Correlation-Id, el identificador que te pedirá soporte, y puedes enviarlo tú en tus solicitudes con hasta 64 caracteres. Las respuestas 429 y 503 traen Retry-After. El contrato se versiona con la cabecera X-Api-Version, que la API devuelve en cada respuesta; si la envías con un valor no admitido, responde 400 con el codEstado 3007 (version_no_soportada). La versión vigente del contrato es 2026-11-16.

Guías: Errores, Respuestas y Versionado.

Estado del servicio y OpenAPI#

La ruta pública GET /estado, sin API Key, informa si el servicio está operativo, degradado o caído, la disponibilidad de los últimos 90 días y los incidentes de ese período; la página Estado del servicio muestra los mismos datos. Si quieres alertas propias, consúltala como máximo una vez por minuto; cada IP puede hacer hasta 60 consultas por minuto. El objetivo de disponibilidad de la API en producción es de 99,9 % mensual.

El contrato completo está publicado en formato OpenAPI. La descarga admite ETag y If-None-Match para revalidar sin descargar de nuevo, y responde comprimida cuando envías Accept-Encoding: gzip. También tienes una colección de Postman, con su environment, que puedes usar en Postman, Bruno o Newman.

Guías: Estado del servicio, Continuidad y salida, Referencia API y Colecciones.

SDK oficiales#

Los SDK para .NET, Node.js, Python, Java y PHP salen en la versión 1.0.0 y cubren la emisión, el seguimiento, el cupo, las consultas al SRI, el perfil del emisor, el estado del servicio y los catálogos. Resuelven por ti la autenticación, la Idempotency-Key, los reintentos ante cortes de red y respuestas 408, 425, 500, 502, 503 y 504, la espera del Retry-After, la verificación de la firma de los webhooks que recibes y el seguimiento hasta un estado final. Los destinos de webhooks se administran desde el portal, el CLI, el servidor MCP o la API REST. Además leen el estado del servicio y los catálogos del SRI. Cada comprobante tiene su propio tipo de solicitud, devuelven objetos tipados con los mismos campos de la API y lanzan una excepción por categoría de error con el codEstado.

Lenguaje Paquete Instalación
.NET Ecuafact.Sdk y Ecuafact.Sdk.Core dotnet add package Ecuafact.Sdk
Node.js @ecuafact/sdk npm install @ecuafact/sdk
Python ecuafact pip install ecuafact
Java com.ecuafact:sdk Dependencia Maven o Gradle com.ecuafact:sdk:1.0.0
PHP ecuafact/sdk composer require ecuafact/sdk

Guías: SDKs, .NET, Node.js, Python, Java y PHP.

CLI#

El CLI ecuafact también sale en 1.0.0. Desde la terminal o desde un script, crea un comprobante de ejemplo, lo valida, lo emite, espera el resultado del SRI y descarga el RIDE y el XML. Emite desde archivos JSON, carpetas, CSV o Excel con una plantilla de mapeo, vigila una carpeta donde tu ERP deja los comprobantes, lista operaciones, consulta tu cuenta, tu cupo y el perfil del emisor, hace las consultas al SRI, muestra el estado del servicio (ecuafact estado-servicio) y los catálogos (ecuafact catalogos), administra y prueba tus destinos de webhooks, y diagnostica tu conexión con doctor. Trabaja con los entornos sandbox y produccion, o con un entorno propio que defines con la URL de tu servidor, guarda la API Key sin mostrarla o la lee de ECUAFACT_API_KEY, y en producción exige confirmar las operaciones que emiten o cambian datos. Se instala con npm (@ecuafact/cli), Scoop o Homebrew.

Guías: CLI de Ecuafact, Emitir con el CLI, Emitir desde CSV o Excel, Vigilar una carpeta y Referencia de comandos.

Servidor MCP, agentes y skill#

El servidor MCP de Ecuafact conecta a Claude, ChatGPT, Cursor, VS Code o a tu propio agente con tu cuenta. Se accede con OAuth 2.1, no con la API Key, y cada agente recibe los permisos y los RUC que tú eliges, que puedes editar o revocar en Integración > Agentes IA. Los endpoints son https://mcp-staging.mynexusapi.com/mcp para pruebas y https://mcp.mynexusapi.com/mcp para producción. Las herramientas consultan el contexto, el cupo y las operaciones, descargan el RIDE y el XML, hacen las consultas al SRI, validan comprobantes y, con el permiso de emitir, los emiten. El agente también consulta el estado del servicio y los catálogos del SRI, y puede administrar el perfil del emisor y los destinos de webhooks con los permisos que concedas en la pantalla de consentimiento. Puedes pedir que cada emisión espere tu confirmación en el portal, y un sistema sin persona se conecta con un bot que usa client_credentials.

El servidor MCP de documentación, público y de solo lectura, está en https://docsapi.ecuafact.com/mcp y ofrece seis herramientas para buscar y leer las guías, explicar un codEstado, obtener un ejemplo de comprobante y consultar la referencia de la API. Para que un asistente de programación escriba tu integración sin inventar campos, el skill de Ecuafact le enseña la API y se instala en Claude Code, GitHub Copilot, Cursor y otros agentes compatibles con Agent Skills. La documentación también se publica como llms.txt, llms-full.txt y Markdown por guía, y cada guía tiene una sección «Para agentes» con un texto listo para pegar en tu agente.

Guías: MCP y asistentes, Skill para asistentes de IA y Instrucciones para agentes de IA.

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.