Changelog

Cambios del API y de la documentacion, con fecha. Toda guia o contrato publico que cambie se registra aqui, con el impacto y tu accion.

Formato:

  • Que cambio. El cambio y el recurso afectado.
  • Impacto. Que puede romperse.
  • Que hacer. La accion concreta; si no hay que hacer nada, se dice.

2026-10-05#

SDK .NET: paquetes publicados en NuGet#

  • Que cambio. Los paquetes Ecuafact.Sdk y Ecuafact.Sdk.Core quedan publicados en NuGet: licencia MIT, README, icono, notas de version y PackageProjectUrl hacia SDK .NET. Se agrega scripts/Pack-Sdk.ps1 para generar los .nupkg y validar su metadata.
  • Impacto. Ninguno sobre el contrato del API.
  • Que hacer. Nada. Instalacion: dotnet add package Ecuafact.Sdk.

SDK PHP: repositorio publico y paquete en Packagist#

  • Que cambio. El SDK PHP queda en su propio repositorio publico (Ecuanexus/ecuafact-sdk-php), con licencia MIT, README publico y composer.json publicado en Packagist como ecuafact/sdk. Se aplica la misma semantica de reintentos que .NET: reintenta 429 y 503 respetando Retry-After, reintenta descargas transitorias y expone EmisionResultado->correlationId.
  • Impacto. Ninguno sobre el contrato del API.
  • Que hacer. Nada. Instalacion: composer require ecuafact/sdk.

SDK Node.js y Java: publicados y con paridad de reintentos#

  • Que cambio. Los SDK Node.js y Java ahora reintentan 429 respetando Retry-After (tambien en 503), reintentan descargas transitorias, exponen la correlacion en EmisionResultado y usan la misma regla de reintento (solo GET o POST/PUT con Idempotency-Key). Node.js queda publicado en npm; Java queda publicado en Maven Central (compilado para Java 17).
  • Impacto. Ninguno sobre el contrato del API.
  • Que hacer. Nada. Instalacion: Node.js npm install @ecuafact/sdk; Java com.ecuafact:sdk.

SDK Python: publicado en PyPI#

  • Que cambio. El SDK Python (ecuafact) queda publicado en PyPI, con licencia MIT, README publico y la misma semantica de reintentos que los demas SDK: 429 respetando Retry-After, reintento en descargas y EmisionResultado.correlation_id.
  • Impacto. Ninguno sobre el contrato del API.
  • Que hacer. Nada. Instalacion: pip install ecuafact.

SDK .NET: reintentos, correlacion y limpieza de contrato#

  • Que cambio. El SDK .NET ahora reintenta 429 respetando Retry-After (tambien en 503), aplica el reintento a descargas y al reemplazo de logo, expone EmisionResultado.CorrelationId, ya no muta EcuafactClientOptions, y retira ListarRecibidosAsync (el listado de recibidos no forma parte del contrato publico). Guia: SDK .NET.
  • Impacto. Si usabas ListarRecibidosAsync, deja de estar disponible; ante 429 el cliente espera y reintenta en lugar de fallar de inmediato.
  • Que hacer. Sustituye ListarRecibidosAsync por ListarEmitidosAsync; si necesitas el identificador de soporte, guarda EmisionResultado.CorrelationId.

2026-10-03#

Onboarding autoservicio: sandbox de pruebas#

  • Que cambio. Nuevo alta autoservicio de sandbox de pruebas en el Portal del Cliente (https://staging-portal.mynexusapi.com/sandbox), en un wizard de 4 pasos (emisor con tu RUC, certificado digital obligatorio, cuenta y confirmacion). Crea un emisor de pruebas con tu RUC y tu certificado, una API Key y el plan "Sandbox MyNexusApi" (5.000 documentos, 2 meses), asignado automaticamente. Se registra la IP de la solicitud y, al confirmar, se envia un correo con la API Key, la URL del API de pruebas, la documentacion y el usuario y clave autogenerada del Portal del Cliente. Solo existe en el ambiente de pruebas. Detalle en Primeros pasos.
  • Impacto. Ninguno sobre el contrato del API. No habilita produccion; el alta de produccion sigue siendo asistida.
  • Que hacer. Nada.

Contrato: version por fecha y cabecera X-Api-Version#

  • Que cambio. La API versiona el contrato por fecha y devuelve la cabecera X-Api-Version en toda respuesta a /v1. La cabecera es opcional en la solicitud; una version inexistente o retirada responde 400 con codigo 306.
  • Impacto. Aditivo y compatible: si no envias X-Api-Version, nada cambia.
  • Que hacer. Nada. Opcional: fija la version y lee la resuelta. Detalle en Versionado.

Descubribilidad: OpenAPI, catalogo de servicios y calendario de versiones#

  • Que cambio. Nuevos recursos /.well-known/api-catalog (RFC 9727) y /.well-known/api-versions.json, mas el encabezado Link: rel="api-catalog". El documento OpenAPI lleva titulo, version por fecha, contacto y licencia.
  • Impacto. Ninguno sobre el contrato; son recursos nuevos.
  • Que hacer. Nada. Enlazables desde Colecciones.

Documentacion para agentes: metadatos citables#

2026-10-02#

Documentacion y guias#

Errores del API: codigos de negocio de base de datos#

  • Que cambio. Varios errores de negocio que se reportaban genericos como 503 (database_unavailable) ahora devuelven su codigo correcto: duplicado (409/401), cupo (429/501), no encontrado (404/502), validacion (400/301) y conflicto de idempotencia (409/403). Sin cambio en el contrato de los codigos ya documentados.
  • Impacto. Si tu integracion trataba esos casos como "servicio no disponible", ahora recibe el codigo especifico del catalogo.
  • Que hacer. Usa el codigo devuelto para decidir reintento o correccion. Ver Errores.

Normalizacion editorial de la documentacion#

  • Que cambio. Todas las guias se alinearon con docs/ESCRITURA-DOCUMENTACION.md: lead de 1-2 frases, rotulo de ambiente de pruebas en la emision y cierre "Siguientes pasos" en cada pagina. primeros-pasos queda como el quickstart y datos-de-prueba como referencia.
  • Impacto. Ninguno sobre el contrato.
  • Que hacer. Nada.

Servidor MCP publicado#

  • Que cambio. El servidor MCP quedo desplegado y disponible por HTTPS: https://mcp.mynexusapi.com/mcp (produccion) y https://mcp-staging.mynexusapi.com/mcp (pruebas), ademas del host interno de desarrollo. Se autentica con X-Api-Key.
  • Impacto. Ninguno sobre el API REST.
  • Que hacer. Nada. Detalle en MCPs y asistentes.

Skill y MCP para asistentes de IA#

  • Que cambio. Nuevo servidor MCP (Streamable HTTP) en {BaseUrl}/mcp autenticado con X-Api-Key; nueva guia MCPs y asistentes y skill para asistentes (paquete .zip). llms.txt ahora enlaza la version .md de cada guia con una descripcion.
  • Impacto. Ninguno sobre el API REST.
  • Que hacer. Nada.

Webhooks: nuevo document.failed#

  • Que cambio. Nuevo evento document.failed (con motivo: estructura_invalida, entrega_no_posible o resultado_desconocido). Se retira document.fiscal_status_changed.
  • Impacto. Si escuchabas document.fiscal_status_changed, deja de llegar.
  • Que hacer. Trata document.authorized, document.rejected y document.failed; actualiza tu handler. Detalle en Webhooks.

Limite de emision: 2 MiB#

  • Que cambio. La emision acepta cuerpos de hasta 2 MiB; por encima responde 413 (codigo 305).
  • Impacto. Los comprobantes mayores al limite se rechazan.
  • Que hacer. Reduce el comprobante. Detalle en Limites.

Correo a varios destinatarios#

  • Que cambio. POST /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/correo acepta varios destinatarios separados por comas en destinatario.
  • Impacto. Ninguno; el campo sigue aceptando un solo correo.
  • Que hacer. Nada. Detalle en Reenviar correo.

Limpieza de contrato#

  • Que cambio. Se retira de la documentacion el listado de comprobantes recibidos. El campo puedeRecibir del contexto se mantiene.
  • Impacto. El endpoint ya no es parte del contrato publico.
  • Que hacer. Usa Comprobantes emitidos.

Como se gestiona#

  • Cada entrada lleva fecha (aaaa-mm-dd).
  • Un cambio incompatible se marca como incompatible y trae la guia de migracion.
  • Los cambios de contrato se anuncian con antelacion y se listan aqui al publicarse.

Siguientes pasos#

No se pudo completar la operacion. Recargar ✕