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

# 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](/v1/guias/emision#secuencial-automatico). 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](/v1/guias/sandbox). 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](/v1/guias/emision), [Factura](/v1/guias/emision-01), [Liquidación de compra](/v1/guias/emision-03), [Nota de crédito](/v1/guias/emision-04), [Nota de débito](/v1/guias/emision-05), [Guía de remisión](/v1/guias/emision-06), [Comprobante de retención](/v1/guias/emision-07), [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida) y [Catálogos](/v1/guias/catalogos).

### 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](/v1/guias/consulta-operacion), [Descargar PDF](/v1/guias/consulta-ride) y [Descargar XML](/v1/guias/consulta-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](/v1/guias/consulta-contexto), [Catálogos](/v1/guias/catalogos#consultar-los-catalogos-por-api), [Perfil del emisor](/v1/guias/perfil-emisor), [Contribuyente por identificación](/v1/guias/consulta-contribuyente), [Contribuyentes por nombre](/v1/guias/consulta-contribuyente-nombre), [Establecimientos de un RUC](/v1/guias/consulta-establecimientos), [Validar identificación](/v1/guias/consulta-identificacion) y [Decodificar clave de acceso](/v1/guias/consulta-clave-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](/v1/guias/autenticacion), [Ambientes y contribuyentes](/v1/guias/ambientes), [Sandbox de pruebas](/v1/guias/sandbox), [Datos de prueba](/v1/guias/datos-de-prueba), [Consumo y cuotas](/v1/guias/consumo), [Límite de request](/v1/guias/limite-de-request), [Límites](/v1/guias/limites) y [Continuidad y salida](/v1/guias/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](/v1/guias/webhooks) y [Verificación de firma](/v1/guias/webhooks-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](/v1/guias/errores), [Respuestas](/v1/guias/respuestas) y [Versionado](/v1/guias/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](/v1/estado) 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](/v1/guias/estado-del-servicio), [Continuidad y salida](/v1/guias/continuidad-y-salida), [Referencia API](/v1/referencia) y [Colecciones](/v1/guias/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](/v1/guias/sdk), [.NET](/v1/guias/sdk-dotnet), [Node.js](/v1/guias/sdk-node), [Python](/v1/guias/sdk-python), [Java](/v1/guias/sdk-java) y [PHP](/v1/guias/sdk-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](/v1/guias/cli), [Emitir con el CLI](/v1/guias/cli-emision), [Emitir desde CSV o Excel](/v1/guias/cli-csv-excel), [Vigilar una carpeta](/v1/guias/cli-vigilar) y [Referencia de comandos](/v1/guias/cli-referencia).

### 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](/v1/guias/mcp), [Skill para asistentes de IA](/v1/guias/skill) y [Instrucciones para agentes de IA](/v1/guias/agentes).
