# Ecuafact API - guía completa > Documentación completa de la API de facturación electrónica del SRI (Ecuador), en un solo archivo para asistentes. Generada desde el contenido versionado de https://docs.mynexusapi.com. Cada guía empieza con un comentario `source_url` y `last_updated`; las guías se separan con `---`. ## Resumen esencial - URL base: pruebas `https://api-sandbox.mynexusapi.com` (sin validez fiscal); producción `https://api.mynexusapi.com`. El ambiente lo define la URL; no se envía en el cuerpo. - Autenticación: cabecera `X-Api-Key` en cada petición, solo desde el backend. API Key ausente, inválida, revocada o vencida: `401`, `codEstado` 3009. En producción, API Key válida pero IP no registrada o no identificable: `403`, `codEstado` 3010; el sandbox acepta cualquier IP. Contribuyente, tipo de comprobante o servicio no habilitados: `403`, `codEstado` 3011. - Flujo: `GET /v1/contexto` (contribuyentes habilitados y su `identificacion`) -> `POST /v1/contribuyentes/{identificacion}/{tipo}` -> `202 Accepted` con `idOperacion` -> `GET /v1/operaciones/{idOperacion}` o webhook -> RIDE/XML en `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` y `.../xml`. - Emisión por tipo: cada comprobante tiene su propia ruta bajo `/v1/contribuyentes/{identificacion}`: `facturas` (`01`), `liquidaciones-compra` (`03`), `notas-credito` (`04`), `notas-debito` (`05`), `guias-remision` (`06`) y `retenciones` (`07`). Para validar sin emitir, agrega `/validar` a la ruta del tipo (`.../{tipo}/validar`): responde `200` con `valido` y `errores`, no crea operación y no exige `Idempotency-Key`. El cuerpo no lleva `infoTributaria.tipoDocumento`: el tipo lo fija la ruta. - Identificación del contribuyente: `{identificacion}` de la ruta es `contribuyentes[].identificacion` de `GET /v1/contexto`, la identificación completa tal como está registrada (por ejemplo, el RUC de 13 dígitos) y el mismo valor de `infoTributaria.ruc`. - `codEstado`: número de 4 dígitos cuyo primer dígito es el `estado` (1 `recibido`, 2 `autorizado`, 3 `rechazado`, 4 `rechazo_configuracion`, 5 `error`, 6 `cancelado`); catálogo completo en https://docs.mynexusapi.com/v1/guias/errores.md. La emisión (`202`), sus rechazos sincrónicos y `GET /v1/operaciones/{idOperacion}` comparten la forma `{ estado, codEstado, msgError, errores, idOperacion, urlEstado, ambiente, tipoDocumento, numeroDocumento, referenciaExterna, claveAcceso, fhRecibido, fhAutorizacion }`; `msgError` se omite sin error y `errores` es siempre un arreglo. El `202` trae `estado` `recibido` con `codEstado` 1001 (`claveAcceso` en `null`) o 1002 (con `claveAcceso`): acepta los dos. Es recibido, no autorizado. `urlEstado` es una URL completa, igual a la cabecera `Location`. En el seguimiento, `recibido` (1001 o 1002) es el único estado no final y `autorizado` (2001) el único con validez fiscal; si no es `autorizado`, `codEstado` da la causa: 3001 rechazo del SRI (su mensaje en `errores`), 3002 comprobante inválido, 4001 emisor no configurado, 4002 firma no válida, 4003 servicio de emisión inactivo, 4004 cupo agotado, 5001 error interno, 5006 entrega no posible, 5007 resultado no confirmado y 6001 operación cancelada. Ante 5007 o 5001 no reemitas. Un comprobante `cancelado` (6001) no se emitió y puedes emitirlo de nuevo con claves nuevas. - Emisión: JSON o XML del SRI (`application/json`, `application/xml` o `text/xml`), cabecera obligatoria `Idempotency-Key` (ASCII, máx. 128). El XML se valida con las mismas reglas que el JSON y la firma entrante se ignora. Reintento con la misma clave y el mismo cuerpo: el mismo `202` con el mismo `idOperacion`. Misma clave con otro cuerpo: `409`, `codEstado` 3005. Número ya emitido: `409`, `codEstado` 3004. Cuerpo máximo 2 MiB (`413`, `codEstado` 3006). - Estructura del comprobante: `origenReferencia`, `referenciaExterna`, `infoTributaria` (`ruc`, `estab`, `ptoEmi` y `secuencial`, opcional: si se omite o va en ceros la plataforma asigna el siguiente), `info` (solo los campos del tipo), la colección del tipo e `infoAdicional`. La clave de acceso la asigna la plataforma; no se envía. No envíes `ambiente`, `tipoEmision`, `version`, `formato` ni `tipoDocumento`: si los envías, en la raíz o en `infoTributaria`, la API responde `422` con `codEstado` 3002, igual que ante cualquier campo desconocido; el detalle por campo llega en `errores`. - Tipos (`tipoDocumento` en la respuesta y en los filtros de consulta): `01` factura, `03` liquidación de compra, `04` nota de crédito, `05` nota de débito, `06` guía de remisión, `07` comprobante de retención. - Errores: los demás endpoints responden JSON plano `{ estado, codEstado, msgError, errores }`; `errores` siempre presente (detalle en validación y mensaje del SRI, `[]` en el resto). Decide por `codEstado` y el estado HTTP, no por `msgError`, que es una descripción fija del código. Correlación en la cabecera `X-Correlation-Id`. La cabecera opcional `X-Additional-Info` (ASCII imprimible, máximo 256 caracteres) sirve para ubicar tu solicitud en soporte y no cambia la respuesta. `4xx`: corregir antes de reintentar. `500`, `502`, `503` y `504`: reintentar con espera y la misma `Idempotency-Key`, respetando `Retry-After` cuando venga. `429` con `codEstado` 5005: reintentar la misma petición después de los segundos de `Retry-After`. `429` con `codEstado` 4004 es cupo agotado: nunca se reintenta; revisa `GET /v1/consumo` y compra un paquete. - Límites: 200 solicitudes por minuto por integración (60 en un sandbox); 20 autenticaciones fallidas por minuto por IP; cuerpo de emisión 2 MiB y 1 MiB en el resto de `POST` y `PUT`. Cada comprobante autorizado o rechazado consume un documento del cupo y uno `cancelado` no lo consume; la revocación de una API Key se aplica en un máximo de 30 segundos. Versión vigente del contrato: `2026-11-16` (cabecera opcional `X-Api-Version`). - Estado y catálogos: `GET /estado` (sin API Key, hasta 60 por minuto por IP) informa si el servicio está `operativo`, `degradado` o `caido`, su disponibilidad de 90 días y los incidentes; `GET /v1/catalogos` lista los catálogos del SRI y `GET /v1/catalogos/{nombre}` devuelve sus filas (se pueden guardar una hora). Guías: [Estado del servicio](https://docs.mynexusapi.com/v1/guias/estado-del-servicio.md) y [Catálogos](https://docs.mynexusapi.com/v1/guias/catalogos.md). - Webhooks: `POST` firmado con `Ecuafact-Signature: t=,v1=`, HMAC-SHA256 de `t + "." + cuerpo_crudo`. Cada entrega trae también las cabeceras de Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), verificables con las librerías oficiales del estándar. Eventos finales: `document.authorized` (`estado` `autorizado`, 2001), `document.rejected` (solo `rechazado` con `codEstado` 3001) y `document.failed` (no se emitió: 3002, `rechazo_configuracion` 4xxx o `error` 5xxx); el cuerpo trae el mismo `estado`, `codEstado`, `msgError`, `errores` y `fhAutorizacion` del seguimiento. `operation.requires_attention` es un aviso no final (el comprobante sigue `recibido` con 1001 o 1002 y el motivo en `errores`; no reemitas y espera su evento `document.*`) y también es el tipo del evento de prueba del portal (`probe` en `"true"`). Un comprobante `cancelado` no genera evento. Entrega al menos una vez y sin orden garantizado: deduplica por `eventType` + `resourceId`. - Asistentes: servidor MCP (Streamable HTTP, OAuth 2.1 con `Authorization: Bearer`; el usuario aprueba permisos y RUC en el portal del cliente, los bots usan `client_credentials`) en `https://mcp-sandbox.mynexusapi.com/mcp` (pruebas) y `https://mcp.mynexusapi.com/mcp` (producción); skill descargable en https://docs.mynexusapi.com/downloads/v1/skills/ecuafact.zip. Guías: [MCP y asistentes](https://docs.mynexusapi.com/v1/guias/mcp.md) y [Skill para asistentes de IA](https://docs.mynexusapi.com/v1/guias/skill.md). - Colección de Postman en el workspace público: https://www.postman.com/ecuafact/ecuafact-api (guia: https://docs.mynexusapi.com/v1/guias/colecciones.md). - Ejemplos listos para ejecutar en .NET, Node.js, Python, PHP y Java, con HTTP directo y con el SDK (consola por tarea y mini app web con webhooks): https://github.com/Ecuanexus/ecuafact-api-ejemplos - CLI `ecuafact` para emitir, seguir y descargar comprobantes desde la terminal (`npm install -g @ecuafact/cli`, Scoop o Homebrew). Sin terminal responde en JSON; `ecuafact schema` describe sus comandos. Guías: [CLI de Ecuafact](https://docs.mynexusapi.com/v1/guias/cli.md) y [Referencia de comandos](https://docs.mynexusapi.com/v1/guias/cli-referencia.md). - Reglas para asistentes: no inventes campos ni códigos; confirma con el usuario antes de emitir; rotula los ejemplos de pruebas; nunca muestres la API Key. Prompts para pegar en un agente de programación: sección «Para agentes» de las guías de SDK, CLI, MCP, primeros pasos, emisión y webhooks. ## Índice - Empezar: Introducción, Primeros pasos, Sandbox de pruebas, Datos de prueba, Ciclo de vida del comprobante, Autenticación, Límite de request, Ambientes y contribuyentes, Buenas prácticas - Emisión: 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, Descargar PDF, Descargar XML, Perfil del emisor - Consulta: Contexto, Seguimiento de una operación, Consumo y cuotas - Consulta SRI: Contribuyente por identificación, Contribuyentes por nombre, Establecimientos de un RUC, Validar identificación, Decodificar clave de acceso - Webhooks: Webhooks, Verificación de firma - SDKs: SDKs, SDK .NET, SDK Node.js, SDK Python, SDK Java, SDK PHP - CLI: CLI de Ecuafact, Emitir con el CLI, Emitir desde CSV o Excel, Vigilar una carpeta, Referencia de comandos del CLI - Recursos: Continuidad y salida, Colecciones, Privacidad de la medición, Changelog - MCPs & Skills: MCP y asistentes, Skill para asistentes de IA, Instrucciones para agentes de IA - Referencia: Respuestas del API, Errores, Catálogos, Estado del servicio, Límites, Glosario, Preguntas frecuentes, Versionado --- # Introducción Emite y consulta comprobantes electrónicos del SRI de Ecuador desde tu sistema con una API REST en JSON, tanto en pruebas como en producción. La API de Ecuafact recibe el comprobante que genera tu sistema (un ERP, un punto de venta, una tienda en línea o un SaaS), se encarga de firmarlo y enviarlo al SRI, y te entrega su autorización junto con el RIDE, el PDF del comprobante. Tu sistema solo envía JSON y consulta el resultado; del resto nos encargamos nosotros. Esta página te da el panorama completo: los conceptos de facturación electrónica que vas a necesitar, las URL de cada ambiente, los tipos de comprobante, lo que puedes hacer con la API y las herramientas que tienes para integrarte. Al final encontrarás por dónde seguir según lo que necesites. ## Conceptos Si nunca antes trabajaste con facturación electrónica, estos son los conceptos mínimos que necesitas para entender el resto de la documentación. Si ya los conoces, puedes pasar directamente a [Por dónde empezar](#por-donde-empezar). - **SRI.** El Servicio de Rentas Internas es la autoridad tributaria de Ecuador. Define qué es un comprobante válido y es quien lo autoriza. - **Comprobante electrónico.** Documento tributario (factura, nota de crédito, retención, etc.) que se emite como archivo firmado digitalmente y se envía al SRI. Solo tiene validez cuando el SRI lo **autoriza**. - **Contribuyente y RUC.** El contribuyente es la persona o empresa que emite; se identifica con su RUC (Registro Único de Contribuyentes, 13 dígitos). Cada emisor necesita un certificado de firma electrónica. - **Numeración.** Cada comprobante tiene un número `estab`-`ptoEmi`-`secuencial` (por ejemplo `001-001-000000123`): establecimiento, punto de emisión y un consecutivo de 9 dígitos. Si quieres, te asignamos el consecutivo. - **Clave de acceso.** Identificador único de 49 dígitos de cada comprobante ante el SRI. Te la asignamos nosotros; tú la recibes en el seguimiento y la usas para descargar archivos. - **Autorización.** Respuesta del SRI sobre un comprobante: autorizado o rechazado. En la API lo ves en el campo `estado` de la operación. - **RIDE.** Representación impresa del comprobante: el PDF que entregas al cliente. Incluye la clave de acceso y el número de autorización. - **Por qué la emisión es asíncrona.** El SRI puede tardar de segundos a minutos en responder. Por eso la API responde de inmediato `202 Accepted` (el comprobante quedó **recibido**) y te da un `idOperacion`. El resultado del SRI lo conoces después, consultando la operación o recibiendo un webhook. Detalle en [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida). - **Ambientes.** **Pruebas** (sin validez fiscal, para desarrollar) y **producción** (con validez fiscal). Cada uno tiene su URL y su API Key. Todos los términos están en el [Glosario](/v1/guias/glosario). ## URL base | Ambiente | URL base | |---|---| | Pruebas | `https://api-sandbox.mynexusapi.com` | | Producción | `https://api.mynexusapi.com` | Todos los ejemplos de esta documentación usan la URL de pruebas y los [datos de prueba](/v1/guias/datos-de-prueba) publicados, así que puedes ejecutarlos sin riesgo. Cuando tu integración esté lista, cambias a la URL de producción; las diferencias entre los dos ambientes están en [Ambientes y contribuyentes](/v1/guias/ambientes). ## Autenticación Cada petición lleva tu **API Key** en la cabecera `X-Api-Key`. En producción, además, debe salir de una IP registrada para tu integración; el sandbox acepta cualquier IP. Una sola API Key cubre todos los contribuyentes habilitados de tu integración. Para obtener una API Key de pruebas en minutos, crea un [sandbox](/v1/guias/sandbox). Detalle en [Autenticación](/v1/guias/autenticacion). ## Tipos de comprobante | `tipoDocumento` | Comprobante | Cuándo se emite | Guía | |---|---|---|---| | `01` | Factura | Vendes un bien o servicio. | [Factura](/v1/guias/emision-01) | | `03` | Liquidación de compra | Compras a una persona que no puede emitirte factura. | [Liquidación de compra](/v1/guias/emision-03) | | `04` | Nota de crédito | Anulas o reduces el valor de una factura (devolución, descuento posterior). | [Nota de crédito](/v1/guias/emision-04) | | `05` | Nota de débito | Aumentas el valor de una factura (intereses, recargos). | [Nota de débito](/v1/guias/emision-05) | | `06` | Guía de remisión | Trasladas mercadería. | [Guía de remisión](/v1/guias/emision-06) | | `07` | Comprobante de retención | Retienes impuestos al pagar a un proveedor. | [Comprobante de retención](/v1/guias/emision-07) | El seguimiento de la operación devuelve el tipo en `tipoDocumento`. Al emitir, el tipo lo fija la ruta: envía cada comprobante a la ruta de su tipo y no incluyas `infoTributaria.tipoDocumento` en el cuerpo. ## Qué puedes hacer | Método | Ruta | Para qué sirve | Guía | |---|---|---|---| | `GET` | `/v1/contexto` | Ver tu integración y los contribuyentes habilitados. | [Contexto](/v1/guias/consulta-contexto) | | `POST` | `/v1/contribuyentes/{identificacion}/facturas` | Emitir una factura. | [Factura](/v1/guias/emision-01) | | `POST` | `/v1/contribuyentes/{identificacion}/liquidaciones-compra` | Emitir una liquidación de compra. | [Liquidación de compra](/v1/guias/emision-03) | | `POST` | `/v1/contribuyentes/{identificacion}/notas-credito` | Emitir una nota de crédito. | [Nota de crédito](/v1/guias/emision-04) | | `POST` | `/v1/contribuyentes/{identificacion}/notas-debito` | Emitir una nota de débito. | [Nota de débito](/v1/guias/emision-05) | | `POST` | `/v1/contribuyentes/{identificacion}/guias-remision` | Emitir una guía de remisión. | [Guía de remisión](/v1/guias/emision-06) | | `POST` | `/v1/contribuyentes/{identificacion}/retenciones` | Emitir un comprobante de retención. | [Comprobante de retención](/v1/guias/emision-07) | | `POST` | `/v1/contribuyentes/{identificacion}/facturas/validar` | Validar sin emitir; usa la misma ruta del tipo seguida de `/validar`. | [Validar sin emitir](/v1/guias/emision#validar-sin-emitir) | | `GET` | `/v1/operaciones/{idOperacion}` | Seguir una emisión hasta su autorización. | [Seguimiento de una operación](/v1/guias/consulta-operacion) | | `GET` | `/v1/operaciones` | Listar las operaciones de un contribuyente por fecha. | [Listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente) | | `GET` | `/v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | Descargar el RIDE (PDF). | [Descargar PDF](/v1/guias/consulta-ride) | | `GET` | `/v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | Descargar el XML. | [Descargar XML](/v1/guias/consulta-xml) | | `GET` | `/v1/contribuyentes/{identificacion}/perfil` | Ver el perfil del emisor (datos que salen en el RIDE). | [Perfil del emisor](/v1/guias/perfil-emisor) | | `PUT` | `/v1/contribuyentes/{identificacion}/perfil` | Actualizar el perfil del emisor. | [Perfil del emisor](/v1/guias/perfil-emisor) | | `POST` | `/v1/contribuyentes/{identificacion}/perfil/logo` | Cambiar el logo del RIDE. | [Perfil del emisor](/v1/guias/perfil-emisor) | | `GET` | `/v1/consumo` | Ver tu cupo de documentos. | [Consumo y cuotas](/v1/guias/consumo) | | `GET` | `/v1/catalogos` y `/v1/catalogos/{nombre}` | Consultar los códigos del SRI (impuestos, formas de pago y otros). | [Catálogos](/v1/guias/catalogos) | | `GET` | `/estado` | Ver el estado del servicio, sin API Key. | [Estado del servicio](/v1/guias/estado-del-servicio) | | `GET` | `/v1/consultas/contribuyentes/{identificacion}` | Consultar un contribuyente en el SRI. | [Contribuyente por identificación](/v1/guias/consulta-contribuyente) | | `GET` | `/v1/consultas/contribuyentes` | Buscar contribuyentes por nombre. | [Contribuyentes por nombre](/v1/guias/consulta-contribuyente-nombre) | | `GET` | `/v1/consultas/establecimientos/{ruc}` | Listar los establecimientos de un RUC. | [Establecimientos de un RUC](/v1/guias/consulta-establecimientos) | | `GET` | `/v1/consultas/identificacion/validar/{numero}` | Validar una cédula o RUC. | [Validar identificación](/v1/guias/consulta-identificacion) | | `GET` | `/v1/consultas/comprobantes/decodificar/{claveAcceso}` | Decodificar una clave de acceso. | [Decodificar clave de acceso](/v1/guias/consulta-clave-acceso) | El cuerpo de los seis tipos comparte la misma estructura, que describe [Comprobantes electrónicos](/v1/guias/emision). Para validar sin emitir, usa la misma ruta del tipo seguida de `/validar`. En las rutas de contribuyente, `{identificacion}` es el valor `identificacion` que devuelve `GET /v1/contexto`, es decir, la identificación completa del contribuyente (para un RUC, sus 13 dígitos), la misma que va en `infoTributaria.ruc`. Además de consultarlo, el resultado de cada emisión te puede llegar por [webhook](/v1/guias/webhooks). ## Formas de integrarte Puedes integrarte con nuestros servicios de facturación de la manera que mejor se adapte a tu sistema y a tu equipo, y combinar varias de ellas. Si quieres controlar cada petición, consume la API directamente desde cualquier lenguaje o plataforma, enviando y consultando JSON por HTTP. La guía [Primeros pasos](/v1/guias/primeros-pasos) te lleva desde la API Key hasta tu primera factura autorizada. Si desarrollas en .NET, Node.js, Python, Java o PHP, puedes integrarte con nuestros [SDK oficiales](/v1/guias/sdk). Ya resuelven la idempotencia, los reintentos y la verificación de los webhooks, para que te concentres en tu sistema. También puedes conectar tu agente de IA, como Claude, ChatGPT o Cursor, con nuestros servicios de facturación mediante el [servidor MCP](/v1/guias/mcp), para que consulte tus comprobantes o emita por ti con los permisos que le concedas. Y si programas con un asistente de IA, el [skill para asistentes](/v1/guias/skill) le enseña la API para que te ayude a construir tu integración. Si necesitas hacer revisiones rápidas, emitir desde los archivos que genera tu ERP o conectar la facturación con un proceso automatizado, puedes usar el [CLI de Ecuafact](/v1/guias/cli) desde tu terminal o desde tus scripts. Y si prefieres explorar la API antes de escribir código, importa nuestra [colección de Postman](/v1/guias/colecciones). En las guías, cada ejemplo aparece en pestañas **HTTP**, **SDK** y **CLI**, para que veas la misma operación con la herramienta que elegiste. ## Por dónde empezar | Si eres... | Empieza por | Después | |---|---|---| | Nuevo en facturación electrónica | [Conceptos](#conceptos) (arriba) y [Ciclo de vida](/v1/guias/ciclo-de-vida) | [Primeros pasos](/v1/guias/primeros-pasos) | | Desarrollador que quiere emitir hoy | [Sandbox de pruebas](/v1/guias/sandbox) | [Primeros pasos](/v1/guias/primeros-pasos) | | Integrador con un SDK | [SDKs](/v1/guias/sdk) | [Comprobantes electrónicos](/v1/guias/emision) | | Quien quiere emitir desde la terminal, scripts o archivos de su ERP | [CLI de Ecuafact](/v1/guias/cli) | [Emitir desde CSV o Excel](/v1/guias/cli-csv-excel) | | Quien prepara el paso a producción | [Datos de prueba](/v1/guias/datos-de-prueba) (casos) | [Ambientes y contribuyentes](/v1/guias/ambientes#como-pasar-a-produccion) | | Quien busca un campo, límite o código | [Errores](/v1/guias/errores), [Límites](/v1/guias/limites), [Catálogos](/v1/guias/catalogos) | [Referencia API](/v1/referencia) | | Quien integra un agente de IA | [MCPs](/v1/guias/mcp) | [Agentes](/v1/guias/agentes) | ## Siguientes pasos - [Sandbox de pruebas](/v1/guias/sandbox): consigue tu API Key de pruebas en unos 10 minutos. - [Primeros pasos](/v1/guias/primeros-pasos): emite tu primera factura y descarga su RIDE. - [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida): qué pasa entre el envío y la autorización. - [Referencia API](/v1/referencia): la especificación OpenAPI interactiva. --- # Primeros pasos Emite tu primera factura en el ambiente de pruebas, sigue su autorización hasta el final y descarga su RIDE, paso a paso. Esta guía te lleva desde la API Key hasta tu primer comprobante autorizado. En seis pasos configuras tu credencial, consultas para qué contribuyentes puedes emitir, envías una factura, sigues su autorización y descargas su RIDE, el PDF que se entrega al cliente. Cada paso trae el ejemplo listo para copiar, la respuesta que deberías ver y cómo comprobar que funcionó antes de seguir. Puedes seguir cada ejemplo de tres formas, en pestañas: llamando a la API por HTTP desde tu lenguaje, con nuestro [SDK oficial](/v1/guias/sdk) de ese lenguaje o desde la terminal con nuestro [CLI de Ecuafact](/v1/guias/cli). Te recomendamos elegir la que vas a usar en tu integración; el resultado es el mismo. Si nunca antes trabajaste con facturación electrónica, te recomendamos leer primero la sección [Conceptos de la Introducción](/v1/guias/introduccion#conceptos). En unos cinco minutos explica qué es el SRI, qué significa que un comprobante esté autorizado y qué es la clave de acceso, tres ideas que esta guía usa todo el tiempo. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Todo lo que emitas en esta guía va a > `https://api-sandbox.mynexusapi.com`. ## 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: ```text Integra la API de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, instálala 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/primeros-pasos.md antes de escribir código; no inventes campos. Primero detecta cómo se integra este proyecto. Si ya usa el SDK de Ecuafact, el CLI ecuafact o el MCP de Ecuafact, sigue con esa vía (las guías sdk-dotnet, sdk-node, sdk-python, sdk-java, sdk-php, cli y mcp traen su propio prompt). Si no usa ninguna, recomiéndame la que mejor encaje, con una frase de motivo, y espera mi respuesta: el SDK de Ecuafact en el lenguaje del proyecto, el CLI ecuafact para probar o automatizar desde la terminal, el MCP para operar mi cuenta desde un asistente, o HTTP directo con la guía de emisión. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Valida la factura con POST /v1/contribuyentes/{identificacion}/facturas/validar y, solo si valida, emítela con POST /v1/contribuyentes/{identificacion}/facturas, una Idempotency-Key estable y una referenciaExterna propia; no envíes infoTributaria.tipoDocumento en el cuerpo. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide por estado y codEstado, usa urlEstado tal cual y lee errores como arreglo. Ejecuta una validación y una emisión de prueba e informa solo el estado, el codEstado y la claveAcceso, y cualquier acción que yo deba hacer. ``` ## Antes de empezar - [ ] Una API Key de pruebas. Si todavía no tienes una, crea tu sandbox como se explica en [Sandbox de pruebas](/v1/guias/sandbox); el alta tarda unos 10 minutos. - [ ] No necesitas registrar ninguna IP para el sandbox. Al pasar a producción, registra la IP de salida de tu servidor como se explica en [IP en sandbox y producción](/v1/guias/sandbox#ip-en-sandbox-y-produccion). - [ ] Una terminal con cURL o el entorno de tu lenguaje: .NET 8 o superior, Python 3.10 o superior con `requests`, Node.js 18 o superior, PHP 8.2 o superior con la extensión `curl` o Java 17 o superior. Si prefieres el CLI, instálalo con las instrucciones de [CLI de Ecuafact](/v1/guias/cli#instalacion). - [ ] Un editor de texto para guardar el archivo `comprobante.json` del paso 3. ## Paso 0. Configura la variable `ECUAFACT_API_KEY` Todos los ejemplos leen la API Key de la variable de entorno `ECUAFACT_API_KEY`. Así no la escribes dentro del código ni la subes por error a tu repositorio. En Windows PowerShell (vale para la ventana actual): ```powershell $env:ECUAFACT_API_KEY = "pega_aqui_tu_api_key" ``` Para que quede guardada en las ventanas nuevas, ejecuta también `setx ECUAFACT_API_KEY "pega_aqui_tu_api_key"` y abre otra terminal. En macOS o Linux (bash o zsh): ```bash export ECUAFACT_API_KEY="pega_aqui_tu_api_key" ``` Los ejemplos cURL usan sintaxis bash (`$ECUAFACT_API_KEY` y `\` al final de línea). En Windows ejecútalos desde Git Bash o WSL, o usa los ejemplos de tu lenguaje. **Cómo sabes que funcionó:** en PowerShell, `echo $env:ECUAFACT_API_KEY`; en bash, `echo $ECUAFACT_API_KEY`. Debe imprimir tu API Key, no una línea vacía. > [!WARNING] > La API Key da acceso a emitir en nombre de tus contribuyentes. No la pegues en > código de navegador, capturas de pantalla ni repositorios. Si se filtra, rótala > en el Portal del Cliente (**Cuenta > API Keys**). ## Paso 1. Obtén tu API Key de pruebas Si ya tienes una API Key de pruebas, salta al paso 2. 1. Abre `https://portal.mynexusapi.com/sandbox`. 2. Completa tus nombres, apellidos, correo y celular, confirma el celular con el código que llega por WhatsApp y crea tu clave con el enlace que llega a tu correo. El detalle está en [Sandbox de pruebas](/v1/guias/sandbox). 3. Ingresa al Portal del Cliente, abre **Pruebas** y pulsa **Generar** en "API Key de pruebas" (si ya tenías una, el botón es **Rotar**). Copia la API Key, que se muestra una sola vez, en la variable del paso 0. 4. Agrega tu RUC y tu certificado en **Contribuyentes > Agregar RUC**. El detalle está en [Sandbox de pruebas](/v1/guias/sandbox#agrega-tu-ruc-y-tu-certificado). **Resultado esperado:** la pantalla "Tu cuenta está creada" al terminar el alta y, dentro del portal, tu API Key de pruebas copiada desde **Pruebas**. **Cómo sabes que funcionó:** la consulta del paso 2 responde 200. Si responde 401, revisa la [tabla de errores](#si-algo-falla). ## Paso 2. Consulta tu contexto `GET /v1/contexto` devuelve los [contribuyentes](/v1/guias/glosario) para los que tu API Key puede emitir. Lo necesitas porque el valor `identificacion` de esta respuesta es el que va en la ruta de emisión y, como [RUC](/v1/guias/glosario) del emisor, dentro del comprobante. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/contexto" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/contexto"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/contexto", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como contexto.mjs y ejecuta: node contexto.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contexto")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; // client: cliente EcuafactClient - ver SDK .NET Contexto contexto = await client.GetContextoAsync(); Console.WriteLine(contexto.Contribuyentes![0].Identificacion); ``` ```python-sdk from ecuafact import EcuafactClient # client: cliente EcuafactClient - ver SDK Python contexto = client.get_contexto() print(contexto.contribuyentes[0].identificacion) ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; // client: cliente EcuafactClient - ver SDK Node.js const contexto = await client.getContexto(); console.log(contexto.contribuyentes[0].identificacion); ``` ```php-sdk getContexto(); echo $contexto->contribuyentes[0]->identificacion; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.contracts.Contexto; // client: cliente EcuafactClient - ver SDK Java Contexto contexto = client.getContexto(); System.out.println(contexto.contribuyentes().get(0).identificacion()); ``` ```bash-cli # Una sola vez: guarda tu API Key en el CLI para el entorno de pruebas. ecuafact login --entorno sandbox # Muestra tu integración y sus contribuyentes, en tabla. ecuafact cuenta --entorno sandbox ``` **Resultado esperado** (`200 OK`; tus valores serán los de tu sandbox): ```json { "idCliente": "1f2e3d4c-5b6a-4789-9012-abcdef012345", "nombre": "Integracion de ejemplo", "contribuyentes": [ { "identificacion": "0123456789001", "puedeEmitir": true, "puedeRecibir": true, "tiposComprobante": [ "01", "03", "04", "05", "06", "07" ] } ] } ``` | Campo | Tipo | Descripción | |---|---|---| | `idCliente` | string (UUID) | Identificador de tu integración. | | `nombre` | string | Nombre de tu integración. | | `contribuyentes` | array | Contribuyentes habilitados para tu API Key en este ambiente. Vacío si no tienes ninguno. | | `contribuyentes[].identificacion` | string | Identificación completa del contribuyente: su RUC de 13 dígitos o la identificación con la que está registrado. Va en la ruta `/v1/contribuyentes/{identificacion}/...` y en `infoTributaria.ruc`. | | `contribuyentes[].puedeEmitir` | boolean | `true` si puedes emitir para este contribuyente. | | `contribuyentes[].puedeRecibir` | boolean | Indica si el contribuyente tiene habilitada la recepción. No afecta la emisión. | | `contribuyentes[].tiposComprobante` | array de string | Códigos de comprobante habilitados: `01` factura, `03` liquidación de compra, `04` nota de crédito, `05` nota de débito, `06` guía de remisión, `07` comprobante de retención. | **Cómo sabes que funcionó:** el código HTTP es `200`, ves al menos un contribuyente con `puedeEmitir: true` y `tiposComprobante` incluye `"01"`. Anota su `identificacion`: es la que usas en la ruta y en `infoTributaria.ruc`. En esta guía usamos la identificación de los [datos de prueba](/v1/guias/datos-de-prueba), `0123456789001`, en la ruta y en `infoTributaria.ruc`. Si tu sandbox tiene otro RUC, reemplázalo por tu valor en los pasos 3 a 5. ## Paso 3. Emite la factura ### Prepara el archivo `comprobante.json` Guarda este JSON como `comprobante.json` en la carpeta desde la que ejecutarás los ejemplos. Antes de guardarlo, cambia: - `infoTributaria.ruc`: tu `identificacion` del paso 2. - `estab` y `ptoEmi`: el [establecimiento y punto de emisión](/v1/guias/glosario) que registraste en el alta del sandbox (por defecto `001` y `001`). - `info.fechaEmision`: la fecha de hoy en formato `dd/MM/yyyy`. ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001" }, "info": { "fechaEmision": "10/11/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE EJEMPLO", "direccionComprador": "DIRECCION DE PRUEBAS", "totalSinImpuestos": 100.00, "totalDescuento": 0.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 100.00, "valor": 15.00 } ], "propina": 0.00, "importeTotal": 115.00, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 115.00 } ] }, "detalles": [ { "codigoPrincipal": "SERV-001", "descripcion": "Servicio de ejemplo", "cantidad": 2, "precioUnitario": 50.00, "descuento": 0.00, "precioTotalSinImpuesto": 100.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 100.00, "valor": 15.00 } ] } ] } ``` El tipo de comprobante lo fija la ruta, así que el cuerpo no lleva `infoTributaria.tipoDocumento`. `POST /v1/contribuyentes/{identificacion}/facturas` emite una factura (`01`). Si necesitas otro tipo, usa su ruta: `.../liquidaciones-compra` (`03`), `.../notas-credito` (`04`), `.../notas-debito` (`05`), `.../guias-remision` (`06`) o `.../retenciones` (`07`). Para revisar el cuerpo sin emitir, usa la misma ruta con `/validar`: para la factura, `POST /v1/contribuyentes/{identificacion}/facturas/validar`. Cómo cuadran los totales (si no cuadran, la API responde `422`): | Cálculo | Valor | |---|---| | `precioTotalSinImpuesto` = `cantidad` x `precioUnitario` - `descuento` = 2 x 50.00 - 0.00 | 100.00 | | IVA de la línea (`codigo` `2`, `codigoPorcentaje` `4` = 15 %) = 100.00 x 15 % | 15.00 | | `totalSinImpuestos` = suma de `precioTotalSinImpuesto` | 100.00 | | `importeTotal` = `totalSinImpuestos` + IVA + `propina` = 100.00 + 15.00 + 0.00 | 115.00 | | Suma de `pagos[].total` (debe ser igual a `importeTotal`) | 115.00 | | Campo | Para qué sirve | |---|---| | `origenReferencia` | Nombre de tu sistema (hasta 64 caracteres). Obligatorio. | | `referenciaExterna` | Tu identificador interno del documento (hasta 128 caracteres), por ejemplo tu número de factura. Obligatorio. | | `infoTributaria.secuencial` | No aparece en el ejemplo a propósito: nosotros asignamos el siguiente número. Ver [El secuencial](#el-secuencial). | | `info.tipoIdentificacionComprador` | `05` cédula, `04` RUC, `06` pasaporte, `07` consumidor final, `08` identificación del exterior. | | `info.propina` y `info.moneda` | Obligatorios en factura: `propina` puede ser `0.00`; `moneda` es `DOLAR`. | | `info.pagos[].formaPago` | `01` es "sin utilización del sistema financiero" (efectivo). El catálogo completo está en [Catálogos](/v1/guias/catalogos). | No envíes `claveAcceso`, `ambiente`, `tipoEmision`, `version` ni `formato`: nosotros los asignamos y, si los envías, la API responde `422` con el `codEstado` 3002 (`comprobante_invalido`). Los campos de cada tipo de comprobante están en [Factura](/v1/guias/emision-01). ### El secuencial El [secuencial](/v1/guias/glosario) es el número consecutivo de 9 dígitos del comprobante dentro de su serie (`estab` + `ptoEmi` + tipo de comprobante + ambiente). Tienes dos opciones, válidas en pruebas y en producción: | Opción | Qué envías | Qué pasa | |---|---|---| | Automático (recomendado para empezar) | Omites `secuencial`, o envías `"000000000"` | Asignamos el siguiente número libre de la serie. Lo ves dentro de la `claveAcceso` del paso 4. | | Explícito | Un número de 1 a 999999999, solo dígitos, máximo 9 (por ejemplo `"000000124"` o `"124"`) | Se usa ese número. Si ya existe un comprobante autorizado o pendiente con ese número en la serie, la API responde `409` con el `codEstado` 3004 (`comprobante_duplicado`). | Usa el explícito solo si tu sistema ya lleva su propia numeración. No mezcles las dos opciones en la misma serie sin control: el automático continúa desde el número más alto usado. ### Envía el comprobante La cabecera `Idempotency-Key` es obligatoria. Identifica la intención de emitir este documento: si tu programa reintenta por un corte de red, envía la misma clave y la API devuelve la misma operación en lugar de crear un duplicado. Usa un valor estable, como tu número interno de factura (`FACTURA-2026-0001`) o un UUID v4 guardado junto al documento. Se admiten letras, dígitos y `- _ . : /`, hasta 128 caracteres. ```bash curl -s -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: FACTURA-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} (paso 4) ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas"); peticion.Headers.Add("Idempotency-Key", "FACTURA-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "FACTURA-2026-0001", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'FACTURA-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: FACTURA-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "FACTURA-2026-0001") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; // client: cliente EcuafactClient - ver SDK .NET EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001"); Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado} / codEstado: {resultado.Admission.CodEstado}"); ``` ```python-sdk from ecuafact import EcuafactClient # client: cliente EcuafactClient - ver SDK Python resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001") print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado} / codEstado: {resultado.admission.cod_estado}") ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; // client: cliente EcuafactClient - ver SDK Node.js const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001"); console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado} / codEstado: ${resultado.admission.codEstado}`); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001'); echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . ' / codEstado: ' . $resultado->admission->codEstado; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EmisionResultado; // client: cliente EcuafactClient - ver SDK Java EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001"); System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado() + " / codEstado: " + resultado.admission().codEstado()); ``` ```bash-cli # Envía el comprobante y muestra el estado recibido y el idOperacion de la emisión. ecuafact emitir comprobante.json --entorno sandbox ``` **Resultado esperado:** HTTP `202 Accepted` con este cuerpo: ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "001-001-000000123", "referenciaExterna": "FACTURA-2026-0001", "claveAcceso": null, "fhRecibido": "2026-11-09T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. Todavía no es una autorización del SRI. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu código debe aceptar los dos valores. | | `errores` | array de string | Viene siempre; aquí es una lista vacía. | | `idOperacion` | string (UUID) | Identificador de la [operación](/v1/guias/glosario). Guárdalo, porque lo necesitas en el paso 4. | | `urlEstado` | string | URL completa del seguimiento. Puedes llamarla tal como viene en el paso 4. | | `ambiente` | number | `1` pruebas, `2` producción. | | `tipoDocumento` | string | Tipo de comprobante (`01` factura). | | `numeroDocumento` | string | Número de la factura con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos. | | `referenciaExterna` | string | La `referenciaExterna` que enviaste. | | `claveAcceso` | string o `null` | `null` con el `codEstado` 1001; con el 1002 ya trae la clave de 49 dígitos. En cualquier caso la ves en el paso 4. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. | | `fhAutorizacion` | `null` | La autorización todavía no existe. | La respuesta trae además dos cabeceras: `Location`, con la misma URL de `urlEstado`, y `X-Correlation-Id`, el identificador de la petición, que te conviene incluir si escribes a soporte. Usa el código HTTP para saber si la petición tuvo éxito. Cuando falla, el cuerpo trae además un número en `codEstado`, por ejemplo 3003 (`solicitud_invalida`) en un HTTP `400`, que es el valor con el que programas tu lógica. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). **Cómo sabes que funcionó:** la API responde 202 con `estado` en `recibido`, el `codEstado` 1001 o 1002 y un `idOperacion`. Un 202 significa que el comprobante quedó **recibido**, no autorizado: el SRI todavía no respondió, así que sigue con el paso 4. > [!NOTE] > Si repites el envío con la misma `Idempotency-Key` y el mismo archivo, recibes > un `202` con el mismo `idOperacion` y el estado actual de la operación. Es lo > esperado y no se emite otra factura. Para emitir otra factura usa otra `Idempotency-Key` y otra > `referenciaExterna`. ## Paso 4. Sigue la operación hasta la autorización La emisión es asíncrona: nos encargamos de que el comprobante llegue al SRI y de obtener su respuesta. Eso tarda desde unos segundos hasta varios minutos, y puedes enterarte del resultado de dos formas: - **Seguimiento por consulta** (lo que haces en esta guía): consulta `GET /v1/operaciones/{idOperacion}` cada 10 segundos, con un tope de 5 minutos (30 consultas). No consultes más seguido: cada consulta cuenta para tu [límite de solicitudes](/v1/guias/limite-de-request) (60 por minuto en un sandbox; 200 por minuto por defecto en otras integraciones). - **Webhook** (recomendado en producción): registras una URL en el Portal del Cliente (**Integración > Eventos**) y te enviamos `document.authorized`, `document.rejected` o `document.failed` cuando hay resultado. Cómo probarlo en este quickstart: [Alternativa: recibe el resultado por webhook](#alternativa-recibe-el-resultado-por-webhook). El bucle se detiene cuando hay un resultado final, es decir, cuando `estado` deja de ser `recibido`. Reemplaza el `idOperacion` por el que recibiste en el paso 3. ```bash ID_OPERACION="3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" # el idOperacion del paso 3 for intento in $(seq 1 30); do respuesta=$(curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/$ID_OPERACION" \ -H "X-Api-Key: $ECUAFACT_API_KEY") echo "$respuesta" case "$respuesta" in *'"estado":"recibido"'*) ;; # sin resultado final: sigue esperando *) break ;; # resultado final o error: revisa "Si algo falla" esac sleep 10 done ``` ```csharp using System.Net.Http; using System.Text.Json; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); string idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; // el idOperacion del paso 3 for (int intento = 1; intento <= 30; intento++) { using HttpResponseMessage respuesta = await http.GetAsync($"/v1/operaciones/{idOperacion}"); string cuerpo = await respuesta.Content.ReadAsStringAsync(); Console.WriteLine($"{(int)respuesta.StatusCode} {cuerpo}"); if (!respuesta.IsSuccessStatusCode) { break; } using JsonDocument json = JsonDocument.Parse(cuerpo); string estado = json.RootElement.GetProperty("estado").GetString()!; if (estado != "recibido") { break; } await Task.Delay(TimeSpan.FromSeconds(10)); } ``` ```python import os import time import requests id_operacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" # el idOperacion del paso 3 for intento in range(30): r = requests.get( f"https://api-sandbox.mynexusapi.com/v1/operaciones/{id_operacion}", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) if r.status_code != 200: break if r.json()["estado"] != "recibido": break time.sleep(10) ``` ```javascript // Node.js 18 o superior. Guarda como seguimiento.mjs y ejecuta: node seguimiento.mjs const idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'; // el idOperacion del paso 3 const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms)); for (let intento = 1; intento <= 30; intento++) { const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones/${idOperacion}`, { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); const cuerpo = await res.text(); console.log(res.status, cuerpo); if (res.status !== 200) break; const { estado } = JSON.parse(cuerpo); if (estado !== 'recibido') break; await esperar(10000); } ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; if ($estado !== 200) { break; } $operacion = json_decode($cuerpo, true); if ($operacion['estado'] !== 'recibido') { break; } sleep(10); } ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception String idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; // el idOperacion del paso 3 HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/operaciones/" + idOperacion)) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); for (int intento = 1; intento <= 30; intento++) { HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); String cuerpo = respuesta.body(); System.out.println(respuesta.statusCode() + " " + cuerpo); if (respuesta.statusCode() != 200) { break; } // Busqueda de texto simple para no depender de una libreria JSON. boolean terminado = !cuerpo.contains("\"estado\":\"recibido\""); if (terminado) { break; } Thread.sleep(10_000); } ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; // client: cliente EcuafactClient - ver SDK .NET Operation operacion = await client.GetOperacionAsync(idOperacion); Console.WriteLine($"{operacion.Estado} / {operacion.CodEstado}"); ``` ```python-sdk from ecuafact import EcuafactClient # client: cliente EcuafactClient - ver SDK Python operacion = client.get_operacion(id_operacion) print(operacion.estado, operacion.cod_estado) ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; // client: cliente EcuafactClient - ver SDK Node.js const operacion = await client.getOperacion(idOperacion); console.log(operacion.estado, operacion.codEstado); ``` ```php-sdk getOperacion($idOperacion); echo $operacion->estado . ' ' . $operacion->codEstado; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.contracts.Operation; // client: cliente EcuafactClient - ver SDK Java Operation operacion = client.getOperacion(idOperacion); System.out.println(operacion.estado() + " " + operacion.codEstado()); ``` ```bash-cli # Consulta una vez el estado de la operación. ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox # O emite y espera el resultado del SRI en un solo comando (hasta 180 segundos). ecuafact emitir comprobante.json --esperar --entorno sandbox ``` **Resultado esperado:** las primeras consultas muestran `estado` `recibido`, con el `codEstado` 1001 o, cuando la factura ya tiene clave de acceso, 1002, y sin `msgError`. La última (`200 OK`) se ve así: ```json { "estado": "autorizado", "codEstado": 2001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "001-001-000000123", "referenciaExterna": "FACTURA-2026-0001", "claveAcceso": "0710202601012345678900110010010000001231234567811", "fhRecibido": "2026-11-09T10:15:00-05:00", "fhAutorizacion": "2026-11-09T10:15:18-05:00" } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido` mientras no hay resultado final; después, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Significado y qué hacer en [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). | | `codEstado` | number | Código de 4 dígitos que precisa el resultado; su primer dígito coincide con el `estado`. 2001 es autorizado, y cuando el comprobante no se autorizó dice la causa, por ejemplo 3001 en un rechazo del SRI. Los valores están en [Errores](/v1/guias/errores#codigos-de-resultado-de-una-operacion). | | `msgError` | string | Descripción general del código. Solo aparece cuando el comprobante no se autorizó. | | `errores` | array de string | Detalle del resultado; en un rechazo del SRI trae su mensaje. Viene siempre y aquí es una lista vacía. | | `idOperacion` | string (UUID) | La operación que consultaste. | | `urlEstado` | string | URL completa de este seguimiento. | | `ambiente` | number | `1` pruebas, `2` producción. | | `tipoDocumento` | string | Tipo de comprobante (`01` factura). | | `numeroDocumento` | string o `null` | Número de la factura, `estab-ptoEmi-secuencial`. | | `referenciaExterna` | string o `null` | La `referenciaExterna` que enviaste. | | `claveAcceso` | string o `null` | [Clave de acceso](/v1/guias/glosario) de 49 dígitos que asignamos nosotros. Es `null` mientras el `codEstado` es 1001. La necesitas en el paso 5. | | `fhRecibido` | string | Cuándo recibimos la emisión, en ISO 8601 con zona horaria. | | `fhAutorizacion` | string o `null` | Fecha de autorización. Puede ser `null` aun con `autorizado`, porque algunas autorizaciones no traen fecha. | **Cómo sabes que funcionó:** `estado` es `autorizado`, el `codEstado` es 2001 y `claveAcceso` tiene 49 dígitos. Copia la `claveAcceso` para el paso 5. El secuencial que se asignó aparece en `numeroDocumento` (`001-001-000000123` en el ejemplo). Si el bucle termina con otro resultado: | Resultado | Qué significa | Qué hacer | |---|---|---| | `estado` = `rechazado` y `codEstado` = 3001 (`rechazo_sri`) | El SRI rechazó el comprobante; `errores` trae su mensaje. | Corrige el dato y emite de nuevo con una nueva `Idempotency-Key` y una nueva `referenciaExterna`, sin `secuencial` para que se asigne el siguiente número. Reusar el número rechazado responde `409` con el `codEstado` 3004 (`comprobante_duplicado`). Ver [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). | | `estado` = `rechazado` y `codEstado` = 3002 (`comprobante_invalido`) | El comprobante no pasó la validación fiscal antes de llegar al SRI; `errores` dice qué corregir. | Corrige y reenvía con nueva `Idempotency-Key` y nueva `referenciaExterna`. Si quieres conservar el número, envía en `infoTributaria.secuencial` el mismo secuencial, que ves en el `numeroDocumento` de la respuesta. La respuesta puede traer el mismo `idOperacion`. | | `estado` = `rechazo_configuracion` | Falta o está mal una configuración del emisor, como su firma electrónica; el `codEstado`, de 4001 a 4004, dice cuál. | Corrige la configuración en el Portal del Cliente y reenvía con nueva `Idempotency-Key` y nueva `referenciaExterna`. Ver [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). | | `estado` = `error` | No se pudo emitir; el `codEstado` dice si puedes reenviar. | Sigue la fila de su `codEstado` en [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). Con 5007 (`resultado_no_confirmado`) o 5001 (`error_interno`) no reemitas y escribe a soporte con el `idOperacion`. | | `estado` = `cancelado` | La plataforma canceló el envío antes de emitirlo. | Reenvía con nueva `Idempotency-Key` y nueva `referenciaExterna`. Si repites la misma `referenciaExterna` con el mismo cuerpo, la API te devuelve la operación cancelada y no emite nada. | | Pasaron 5 minutos y `estado` sigue en `recibido` | El SRI todavía no da un resultado final. No es un error. | No reemitas, porque emitir de nuevo puede duplicar el comprobante. Consulta más tarde o espera el webhook, como se explica en [Webhooks](/v1/guias/webhooks#que-hacer-ante-cada-evento). | ### Alternativa: recibe el resultado por webhook En lugar del bucle, o además de él, puedes recibir el resultado en tu servidor. Te lo recomendamos para producción: te avisamos cuando hay resultado y no gastas solicitudes en consultas. Prerequisitos adicionales: - [ ] Una URL pública `https://` (puerto 443) que llegue a tu equipo o servidor. En tu equipo de desarrollo puedes exponer un puerto local con un túnel como ngrok o cloudflared ([Probar en local](/v1/guias/webhooks#probar-en-local)). - [ ] Un receptor que verifique la firma. Copia el de tu lenguaje (.NET, Python, Node.js, PHP o Java) de [Implementación en tu servidor](/v1/guias/webhooks#implementacion-en-tu-servidor) y ejecútalo en el puerto 3000. Pasos: 1. Entra al Portal del Cliente (`https://portal.mynexusapi.com`) y abre **Integración > Eventos**. 2. Pulsa **Nuevo destino**, escribe tu URL (por ejemplo `https://tu-subdominio.ngrok-free.app/webhooks/ecuafact`), deja marcados los tres eventos y pulsa **Crear**. 3. Copia el **secreto** que muestra el portal (se muestra una sola vez) en la variable `ECUAFACT_WEBHOOK_SECRET` de tu receptor y reinícialo. 4. Pulsa **Probar**. En **Entregas** debe aparecer el evento de prueba con estado **Entregado** y `HTTP` `200`. 5. Emite otra factura como en el paso 3, con otra `Idempotency-Key` y otra `referenciaExterna` (por ejemplo `FACTURA-2026-0002` en ambas). **Resultado esperado:** cuando el SRI autoriza, tu receptor recibe un `POST` con la cabecera `Ecuafact-Signature` y este cuerpo: ```json { "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "estado": "autorizado", "codEstado": 2001, "errores": [], "tipoDocumento": "01", "claveAcceso": "0710202601012345678900110010010000001231234567811", "eventType": "document.authorized", "resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "occurredAtUtc": "2026-11-09T15:15:18.1234567Z" } ``` | Campo | Tipo | Descripción | |---|---|---| | `idOperacion` | string (UUID) | La operación que recibiste en el `202` de la emisión. | | `estado` | string | El mismo estado del seguimiento: `autorizado` en `document.authorized`; `rechazado`, `rechazo_configuracion` o `error` en los demás eventos, que además traen `msgError`. | | `codEstado` | number | El mismo `codEstado` del seguimiento, por ejemplo 2001 en `document.authorized`. | | `errores` | array de string | El detalle del resultado, como en el seguimiento. Viene siempre. | | `tipoDocumento` | string | Tipo de comprobante (`01` factura), cuando se conoce. | | `claveAcceso` | string | Clave de acceso de 49 dígitos. Úsala en el paso 5. En `document.failed` puede faltar. | | `eventType` | string | `document.authorized`, `document.rejected` o `document.failed`. | | `resourceId` | string (UUID) | En estos eventos, igual a `idOperacion`. Úsalo con `eventType` para descartar duplicados. | | `occurredAtUtc` | string | Momento del evento en UTC (ISO 8601). | **Cómo sabes que funcionó:** tu receptor imprime `Autorizado` con el `idOperacion` y la `claveAcceso`, y en **Entregas** la entrega figura como **Entregado**. Con esa `claveAcceso` sigue al paso 5. Los demás eventos y qué hacer con cada uno están en [Webhooks](/v1/guias/webhooks#eventos). ## Paso 5. Descarga el RIDE y el XML Con la `claveAcceso` del paso 4 descarga el RIDE (PDF) y el XML del comprobante autorizado: ``` GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml ``` `{identificacion}` es el mismo valor de la ruta de emisión, la `identificacion` del paso 2. Reemplaza la `claveAcceso` del ejemplo por la tuya. ```bash curl -s -o ride.pdf -w "HTTP %{http_code}\n" \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); string claveAcceso = "0710202601012345678900110010010000001231234567811"; // la claveAcceso del paso 4 using HttpResponseMessage respuesta = await http.GetAsync( $"/v1/contribuyentes/0123456789001/comprobantes/{claveAcceso}/ride"); Console.WriteLine($"{(int)respuesta.StatusCode} {respuesta.Content.Headers.ContentType}"); if (respuesta.IsSuccessStatusCode) { await File.WriteAllBytesAsync("ride.pdf", await respuesta.Content.ReadAsByteArrayAsync()); } else { Console.WriteLine(await respuesta.Content.ReadAsStringAsync()); } ``` ```python import os import requests clave_acceso = "0710202601012345678900110010010000001231234567811" # la claveAcceso del paso 4 r = requests.get( f"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/{clave_acceso}/ride", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.headers.get("Content-Type")) if r.status_code == 200: with open("ride.pdf", "wb") as archivo: archivo.write(r.content) else: print(r.text) ``` ```javascript // Node.js 18 o superior. Guarda como ride.mjs y ejecuta: node ride.mjs import { writeFile } from 'node:fs/promises'; const claveAcceso = '0710202601012345678900110010010000001231234567811'; // la claveAcceso del paso 4 const res = await fetch( `https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/${claveAcceso}/ride`, { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, res.headers.get('content-type')); if (res.ok) { await writeFile('ride.pdf', Buffer.from(await res.arrayBuffer())); } else { console.log(await res.text()); } ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . PHP_EOL; if ($estado === 200) { file_put_contents('ride.pdf', $cuerpo); } else { echo $cuerpo . PHP_EOL; } ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception String claveAcceso = "0710202601012345678900110010010000001231234567811"; // la claveAcceso del paso 4 HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/" + claveAcceso + "/ride")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofByteArray()); System.out.println(respuesta.statusCode()); if (respuesta.statusCode() == 200) { Files.write(Path.of("ride.pdf"), respuesta.body()); } else { System.out.println(new String(respuesta.body())); } ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; // client: cliente EcuafactClient - ver SDK .NET ArchivoComprobante ride = await client.DescargarRideAsync("0123456789001", claveAcceso); await File.WriteAllBytesAsync("ride.pdf", ride.Contenido); ``` ```python-sdk from ecuafact import EcuafactClient # client: cliente EcuafactClient - ver SDK Python archivo = client.descargar_ride("0123456789001", clave_acceso) with open("ride.pdf", "wb") as destino: destino.write(archivo.contenido) ``` ```javascript-sdk import { writeFile } from "node:fs/promises"; import { EcuafactClient } from "@ecuafact/sdk"; // client: cliente EcuafactClient - ver SDK Node.js const archivo = await client.descargarRide("0123456789001", claveAcceso); await writeFile("ride.pdf", archivo.contenido); ``` ```php-sdk descargarRide('0123456789001', $claveAcceso); file_put_contents('ride.pdf', $archivo->contenido); ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.contracts.ArchivoComprobante; import java.nio.file.Files; import java.nio.file.Path; // client: cliente EcuafactClient - ver SDK Java ArchivoComprobante archivo = client.descargarRide("0123456789001", claveAcceso); Files.write(Path.of("ride.pdf"), archivo.contenido()); ``` ```bash-cli # Descarga el RIDE y el XML en la carpeta actual. ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo ride,xml --entorno sandbox ``` Para el XML cambia `/ride` por `/xml` en la ruta (en los SDK: `DescargarXmlAsync`, `descargar_xml`, `descargarXml`). Este ejemplo guarda el archivo como `factura.xml` e imprime las cabeceras para que veas `Content-Type`: ```bash curl -s -o factura.xml -D - \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` **Resultado esperado:** | Descarga | HTTP | `Content-Type` | Contenido | |---|---|---|---| | RIDE | `200 OK` | `application/pdf` | El PDF del comprobante. | | XML | `200 OK` | `application/xml` | El XML del comprobante, con nombre sugerido `{claveAcceso}.xml` (cabecera `Content-Disposition`). | | XML pendiente | `404 Not Found` | `application/json` | Si falta la autorización o el archivo, recibes el `codEstado` 3013 (`no_encontrado`). Reintenta la descarga en unos minutos, sin volver a emitir. | **Cómo sabes que funcionó:** el RIDE que descargaste (los ejemplos HTTP y SDK lo guardan como `ride.pdf`) se abre en tu visor de PDF y muestra la clave de acceso y el número de autorización. Con eso completaste la guía. Detalle de cada descarga: [Descargar PDF](/v1/guias/consulta-ride) y [Descargar XML](/v1/guias/consulta-xml). ## Si algo falla Cuando una petición falla, la API responde con un código HTTP de error y un cuerpo con `estado`, `codEstado`, `msgError` y `errores`. En la emisión, esos mismos campos llegan dentro de la forma completa de la respuesta 202, con `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`, porque no se creó ninguna operación: ```json { "estado": "rechazado", "codEstado": 3003, "msgError": "La solicitud no es válida.", "errores": [ "Idempotency-Key: La cabecera Idempotency-Key es obligatoria y debe ser ASCII estable (maximo 128 caracteres)." ], "idOperacion": null, "urlEstado": null, "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": null, "referenciaExterna": "FACTURA-2026-0001", "claveAcceso": null, "fhRecibido": null, "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | Estado que corresponde al código. Su valor coincide con el primer dígito de `codEstado`: 3 es `rechazado`, 4 `rechazo_configuracion` y 5 `error`. | | `codEstado` | number | Código estable de la API, de 4 dígitos. Programa contra este valor. No es el código HTTP. | | `msgError` | string | Descripción fija y breve del código. Puedes mostrarla, pero no decidas con ella. | | `errores` | array de string | Viene siempre. En 3002 (`comprobante_invalido`) trae hasta 20 mensajes, uno por problema, con la ruta del campo (por ejemplo `$.infoTributaria.ruc: Campo obligatorio.`). En 3003 (`solicitud_invalida`) trae el detalle de los parámetros o del cuerpo que no se pudo leer; puede ser más de uno. Corrige todos los que puedas y reenvía. En el resto de errores es una lista vacía (`[]`). | Los errores más probables en este quickstart: | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 3009 (`credenciales_invalidas`) | 401 | Falta la cabecera `X-Api-Key` o la API Key es incorrecta, está revocada o es de otro ambiente. | Corrige: revisa que `ECUAFACT_API_KEY` tenga la API Key completa (paso 0). Si la revocaste, crea otra. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la API Key es correcta pero **tu IP de salida no está registrada** para esa API Key. En sandbox no ocurre por IP. | Registra tu IP en **Cuenta > IP permitidas** del Portal del Cliente ([cómo](/v1/guias/sandbox#si-tu-ip-cambia)). | | 3011 (`acceso_denegado`) | 403 | El contribuyente de la ruta no está habilitado para tu API Key o el tipo de comprobante no está habilitado. | Corrige: usa en la ruta y en `infoTributaria.ruc` la `identificacion` del paso 2. | | 3003 (`solicitud_invalida`) | 400 | Falta `Idempotency-Key` o tiene caracteres no admitidos, el JSON está mal formado, o la `claveAcceso` de la descarga no es válida. | Corrige: agrega la cabecera; valida el JSON (comas, comillas); copia la `claveAcceso` completa. | | 3002 (`comprobante_invalido`) | 422 | El comprobante tiene un campo faltante o mal formado, totales que no cuadran, un `infoTributaria.ruc` distinto de la identificación de la ruta, o un campo que no se envía (`claveAcceso`, `ambiente`, `version`). `errores` dice cuál. | Corrige el campo indicado en `errores` y reenvía con la misma `Idempotency-Key`. Un `422` descuenta un documento de tu cupo como intento, así que valida antes con `/validar`, que no lo descuenta. | | 3004 (`comprobante_duplicado`) | 409 | Ya existe un comprobante autorizado o pendiente con el mismo `estab`, `ptoEmi` y `secuencial`. | Corrige: omite `secuencial` para que se asigne el siguiente, o usa otro número. | | 3005 (`conflicto_idempotencia`) | 409 | Usaste una `Idempotency-Key` que ya se usó con un cuerpo distinto, o una `referenciaExterna` (con el mismo `origenReferencia`) que ya pertenece a otro comprobante. | Corrige: para un comprobante nuevo usa una `Idempotency-Key` y una `referenciaExterna` nuevas; para reintentar, envía exactamente el mismo cuerpo. | | 3013 (`no_encontrado`) | 404 | Descarga del RIDE o XML: el comprobante no existe o aún no está disponible. | Reintenta cuando el `estado` de la operación sea `autorizado`; revisa la `claveAcceso` y la `identificacion` de la ruta. | | 5005 (`limite_solicitudes`) | 429 | Superaste tu límite de solicitudes por minuto (60 en un sandbox), por ejemplo con un bucle de seguimiento sin espera. | Reintenta después de los segundos de la cabecera `Retry-After` y agrega la espera de 10 segundos. | El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida): qué hacer ante cada `estado` y cada `codEstado`. - [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar en bucle. - [Datos de prueba](/v1/guias/datos-de-prueba): provoca cada caso (duplicado, idempotencia, rechazo) antes de ir a producción. - [Comprobantes electrónicos](/v1/guias/emision): estructura de los seis tipos de comprobante. --- # Sandbox de pruebas Crea tu cuenta de pruebas, agrega tu RUC y emite sin validez fiscal; cuando estés listo, pasas a producción desde el mismo portal. Puedes crear tú mismo tu cuenta desde el Portal del Cliente, sin contratos y sin esperar a que alguien te dé acceso. El alta de la cuenta pide solo tus datos, tu correo y tu celular; el RUC y el certificado se agregan después, dentro del portal. El portal puede mostrar la IP desde la que te conectas como referencia para producción; el sandbox no la exige ni la bloquea. Al terminar tienes tu cuenta, una API Key de pruebas y un cupo único de 3.000 documentos, sin renovación automática: todo lo que necesitas para seguir [Primeros pasos](/v1/guias/primeros-pasos) y emitir tu primera factura. El alta de la cuenta tarda unos minutos; agregar el RUC y el certificado, unos pocos más. Lo que emitas en el sandbox se firma y se envía al ambiente de pruebas del SRI, así que se comporta como en producción, pero no tiene validez fiscal. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. El alta está en > `https://portal.mynexusapi.com/sandbox`. Cuando termines de probar, pasas a > producción desde el portal, como se explica en > [Pasar a producción](#pasar-a-produccion). ## 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: ```text Prepara este proyecto para trabajar con mi sandbox de Ecuafact y comprueba que responde. 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/sandbox.md antes de escribir código; no inventes campos. El alta de la cuenta, la carga del RUC y la del certificado las hago yo en el Portal del Cliente; no intentes crearlas ni me pidas el certificado o su password en el chat. Reutiliza el SDK de Ecuafact del proyecto; si no usa ninguno, recomiéndame el SDK de su lenguaje o el CLI ecuafact, con una frase de motivo, y espera mi respuesta; cURL o HTTP directo solo si lo prefiero. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. El sandbox no exige IP registrada: no me pidas registrar la IP. Si la API responde 401 con codEstado 3009, revisa la clave; si aparece un 403 con codEstado 3010 en pruebas, repórtalo como anomalía en lugar de reintentar. Con la clave configurada, consulta el contexto (GET /v1/contexto) con la cabecera X-Api-Key para comprobar que el emisor de pruebas responde y consulta GET /v1/consumo para ver el cupo restante. No emitas nada en este paso y no cambies a producción: ese cambio lo hago yo desde el portal. Ejecuta las consultas e informa solo el RUC del emisor de pruebas, el cupo restante y cualquier acción que yo deba hacer. ``` ## Antes de empezar - [ ] Tus nombres y apellidos, y un correo que puedas revisar, porque ahí llega el enlace para crear tu clave del portal. - [ ] Un celular de Ecuador con WhatsApp que tengas a mano. Ahí llega el código de 6 dígitos con el que confirmas el número, y vence en 10 minutos. - [ ] Una conexión a internet. En el sandbox puedes llamar desde cualquier IP; la lista de IP permitidas se exige al pasar a producción, como se explica en [IP en sandbox y producción](#ip-en-sandbox-y-produccion). - [ ] Para emitir, el RUC de 13 dígitos del emisor con el que vas a probar y su certificado de firma electrónica (`.p12` o `.pfx`) con su password. No hacen falta para crear la cuenta: se piden al agregar el RUC, dentro del portal. ## Cómo funciona El alta tiene tres pasos, que el portal llama Datos, Celular y Clave. Primero escribes tus datos, después confirmas tu celular con un código que llega por WhatsApp y al final creas tu clave con el enlace que te enviamos por correo. La cuenta se crea en el momento en que creas la clave. Después agregas el RUC y el certificado dentro del Portal del Cliente y copias tu API Key de pruebas. ```mermaid flowchart LR A[1. Tus datos] --> B[2. Código de WhatsApp] --> C[3. Correo y clave] C --> D[4. RUC y certificado] --> E[5. API Key de pruebas] ``` ### 1. Tus datos Abre `https://portal.mynexusapi.com/sandbox`. En la pantalla "Crea tu cuenta", completa: | Campo | Obligatorio | Regla | |---|---|---| | Nombres | Sí | De 2 a 100 caracteres. Solo letras, espacios, apóstrofo, guion y punto. | | Apellidos | Sí | De 2 a 100 caracteres. Solo letras, espacios, apóstrofo, guion y punto. | | Correo | Sí | Un correo tuyo o de tu empresa que puedas abrir, escrito sin espacios. No se aceptan correos temporales. | | Celular con WhatsApp | Sí | Celular de Ecuador con WhatsApp: `0991234567`, `+593 99 123 4567` o `593991234567`. Un mismo celular admite hasta 3 cuentas. | | Términos y datos | Sí | Acepta los [Términos y Condiciones y la Política de Protección de Datos Personales](https://legal.ecuafact.com/). | | Comunicaciones | No | Casilla opcional para recibir información sobre nuevos productos y servicios, ofertas o recomendaciones por e-mail/teléfono. | | Verificación de seguridad | Si aparece | Resuélvela antes de continuar. | Pulsa **Continuar**. No se pide RUC, certificado, dirección ni punto de emisión en esta pantalla. Al enviar el formulario te enviamos un código de 6 dígitos por WhatsApp al celular que escribiste. ### 2. Confirma tu celular La pantalla "Ingresa el código" muestra el celular al que enviamos el mensaje. Escribe el código de 6 dígitos y pulsa **Confirmar**. El código vence en 10 minutos y admite 5 intentos; si te equivocas, la misma pantalla te deja corregirlo. Si el código no llega, venció o agotaste los intentos, pulsa **Reenviar código**. El botón se habilita 60 segundos después del último envío, y el código nuevo reemplaza al anterior. Un mismo celular admite hasta 5 códigos en 24 horas. Cada código que pides cuenta para ese máximo, también el que sale al enviar el formulario y el que no llegó a tu celular. Si escribiste mal el número, usa **Cambiar número** para volver al formulario con tus datos ya cargados. Al enviarlo de nuevo te llega otro código. Confirmar el celular todavía no crea la cuenta. Si pasan 24 horas sin que avances en el alta, o 48 horas desde que la empezaste, los datos del formulario se eliminan y empiezas de nuevo. ### 3. Crea tu clave Con el celular confirmado, la pantalla "Revisa tu correo" te avisa que enviamos un correo a tu dirección. El correo se llama "Crea tu clave de Ecuafact" y trae el botón **Crear mi clave**. El enlace vence en 7 días y se usa una sola vez; puedes abrirlo desde cualquier equipo o navegador. Si el correo no llega, revisa la carpeta de correo no deseado y, pasados 60 segundos, pulsa **Reenviar correo**; el enlace nuevo reemplaza al anterior. Un mismo celular admite hasta 5 correos del alta en 24 horas, contando el primero. Si escribiste mal la dirección, usa **Corregir correo** para volver al formulario. Al enviarlo de nuevo, el enlace anterior deja de servir y confirmas otra vez tu celular con un código nuevo, aunque el número sea el mismo. El enlace abre la pantalla "Crea tu clave", que muestra tu correo y pide la clave dos veces. La clave debe tener entre 8 y 128 caracteres, con letras y números. Pulsa **Crear cuenta**. La cuenta se crea en ese momento y la pantalla "Tu cuenta está creada" te ofrece **Ingresar**; entras al Portal del Cliente con tu correo y la clave que acabas de crear. Tienes 7 días desde que confirmaste tu celular para crear la clave, y reenviar el correo no alarga ese plazo. Pasado ese tiempo, los datos del alta se eliminan y empiezas de nuevo. Si tu correo ya tiene una cuenta de Ecuafact, en lugar del enlace recibes el correo "Ya tienes una cuenta de Ecuafact", con el botón **Ingresar**. Entra con tu correo y tu clave; si no la recuerdas, usa **¿Olvidaste tu clave?** en la pantalla de ingreso. ### 4. Agrega tu RUC y tu certificado Entra al Portal del Cliente con tu correo y tu clave, abre **Contribuyentes** y pulsa **Agregar RUC**. Completa: | Campo | Obligatorio | Regla | |---|---|---| | RUC | Sí | Exactamente 13 dígitos. | | Razón social | Sí | Hasta 300 caracteres. | | Teléfono | No | Hasta 40 caracteres. | | Nombre comercial | No | Hasta 300 caracteres. | | Dirección | No | Hasta 400 caracteres. | | Certificado | Sí | Archivo `.p12` o `.pfx` con clave privada. | | Clave del certificado | Sí | La password que abre el archivo. | El certificado debe contener la clave privada. El portal comprueba que la password lo abre y no compara el titular del certificado con el RUC. Con ese certificado firmaremos tus comprobantes de prueba; para pasar a producción debe estar vigente. El alta crea la primera serie del RUC: establecimiento `001` y punto de emisión `001`. Envías esos dos valores en `infoTributaria.estab` e `infoTributaria.ptoEmi` de cada comprobante; si usas otros establecimientos o puntos de emisión, los indicas en la misma solicitud. El secuencial es por RUC, tipo de comprobante, establecimiento, punto de emisión y ambiente: si lo omites, la API asigna el siguiente. En **Pruebas > Emitir prueba** escribes el número con el que quieres probar. Al pulsar **Agregar RUC**, el portal configura el ambiente de pruebas de ese RUC y muestra el mensaje "Espera un momento..." hasta que termina; normalmente tarda unos segundos. Si pasa un minuto sin terminar, el mensaje se cierra y te avisa que recibirás un correo cuando el ambiente esté listo. También recibes un correo al agregar el RUC y otro cuando termina la configuración. La modalidad llega preseleccionada en **Normal**. ### 5. Copia tu API Key de pruebas La API Key de pruebas no se muestra durante el alta: la obtienes dentro del portal. La primera vez que entras, el portal te da la bienvenida y te pregunta si quieres generarla ahora. Si eliges **Generar mi API Key**, se abre la ventana con la clave completa. Si eliges **Ahora no** o cierras el mensaje, no vuelve a aparecer; abre **Pruebas** y pulsa **Generar** en la tarjeta "API Key de pruebas". Cuando ya tienes una clave, esa tarjeta muestra su prefijo y el botón **Rotar**: pulsa **Rotar** y confirma para obtener una nueva. En ambos casos la ventana muestra la API Key completa una sola vez, así que usa **Copiar** y guárdala en la variable `ECUAFACT_API_KEY` o en tu gestor de secretos antes de pulsar **Listo**. Si en **Pruebas** aparece el aviso "Preparando tu ambiente de pruebas", espera unos minutos y vuelve a abrir la página. Para saber si todo funcionó, comprueba que `GET /v1/contexto` con tu API Key responde 200 con tu RUC en `identificacion` y que `tiposComprobante` incluye el tipo que vas a emitir. Esa llamada es el paso 2 de [Primeros pasos](/v1/guias/primeros-pasos). El emisor de pruebas puede tardar unos minutos en quedar listo para emitir. > [!WARNING] > La API Key de pruebas permite emitir comprobantes con tu certificado. Guárdala > en la variable `ECUAFACT_API_KEY` o en tu gestor de secretos. No la volverás a > ver: si la pierdes o crees que se filtró, rótala de nuevo en **Pruebas** del > Portal del Cliente. Al rotarla, la clave anterior deja de funcionar en unos > minutos. ## Qué recibes Este es el resumen de lo que tienes al terminar el alta y dónde encontrar cada dato. | Dato | Valor o dónde llega | |---|---| | API Key de pruebas | En **Pruebas** del Portal del Cliente, con **Generar** la primera vez y **Rotar** después. Se muestra una sola vez, como se explica en [Copia tu API Key de pruebas](#api-key-de-pruebas). | | URL de la API de pruebas | `https://api-sandbox.mynexusapi.com` | | Portal del Cliente | `https://portal.mynexusapi.com`, con tu correo y la clave que creaste. La sección **Pruebas** muestra tu cupo, tus comprobantes de prueba y tus bots MCP de pruebas. | | Paquete de pruebas | 3.000 documentos en total, sin vencimiento ni renovación automática. Lo que te queda lo consultas en [Consumo y cuotas](/v1/guias/consumo). | | Correos de los comprobantes | Se envían solo al correo del titular de tu cuenta, sea cual sea el comprador. | | Límite de solicitudes | 60 por minuto para toda la integración. Cada respuesta trae las cabeceras `X-RateLimit-Limit` y `X-RateLimit-Remaining`; el detalle está en [Límite de request](/v1/guias/limite-de-request). | | Identificación para las rutas | Tu RUC completo, de 13 dígitos. Puedes confirmarla con [Contexto](/v1/guias/consulta-contexto). | ## IP en sandbox y producción En el sandbox, la API acepta la API Key desde cualquier IP. No tienes que registrar la IP de tu equipo, de tu VPN ni la de tu servidor de pruebas. Si la API Key es incorrecta, la respuesta es un 401 con el `codEstado` 3009 (`credenciales_invalidas`). La lista de IP permitidas se aplica en producción. Cuando pases a producción, registra la IP pública de salida de tu servidor antes de llamar a la API. Si llamas desde otra IP, la respuesta es un 403 con el `codEstado` 3010 (`ip_no_autorizada`). ### Si tu IP cambia en producción Tu IP pública cambia, por ejemplo, cuando trabajas desde casa en lugar de la oficina, cuando usas una VPN o cambias de proveedor de internet, y cuando despliegas tu código en un servidor o en la nube. Para seguir llamando a la API desde la red nueva: 1. Entra al Portal del Cliente (`https://portal.mynexusapi.com`) con tu correo y tu clave. 2. Abre **Cuenta > IP permitidas**. Arriba, junto a "Este navegador:", ves la IP desde la que estás conectado al portal. 3. Pulsa **Agregar** y escribe la IP nueva (por ejemplo 190.10.20.30) o un rango en notación CIDR (por ejemplo 190.10.20.0/24). 4. Si quieres comprobar si una IP o un rango ya queda permitido, pulsa **Probar**. 5. Quita con **Quitar** las IP que ya no uses. Ten en cuenta que la IP que muestra el portal es la de tu navegador. Si tu código corre en otro equipo o en un servidor, registra la IP de salida de ese equipo. Los cambios pueden tardar hasta un minuto en aplicarse; sabrás que funcionó cuando `GET /v1/contexto` desde la red nueva responda 200 en lugar de 403. > [!NOTE] > Si quitas todas las IP de producción, la API rechaza todas las peticiones con > un 403. Agrega siempre la IP nueva antes de quitar la anterior. ## Vencimiento El paquete de pruebas no tiene fecha de vencimiento: recibes 3.000 documentos una sola vez. El saldo no se repone al cambiar de mes ni al repetir el alta. Si necesitas más documentos, abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/) y nuestro equipo de soporte amplía tu cupo de pruebas. No puedes aumentarlo por tu cuenta. ## El ambiente lo define la URL El ambiente lo define la URL. Si envías `ambiente` en la raíz o en `infoTributaria`, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`). ## Pasar a producción Cuando estés listo para emitir con validez fiscal, entra al Portal del Cliente y abre **Pasar a producción**. Antes de llamar a la API de producción, registra la IP de salida de tu servidor en **Cuenta > IP permitidas**. El botón se habilita cuando se cumplen las tres condiciones: | Condición | Cómo la cumples | |---|---| | Correo verificado | Ya la cumples al crear tu clave con el enlace del correo. | | Firma electrónica vigente | El certificado que cargaste al agregar el RUC debe seguir vigente. | | Al menos 5 comprobantes de prueba aceptados | Emítelos con tu API Key de pruebas; la sección **Pruebas** muestra cuántos llevas. | Al confirmar, tu cuenta de producción incluye **20 documentos** con vigencia de un año. No necesitas comprar un paquete para pasar; cuando uses esos 20, compra el paquete que necesites en **Consumo**. La pantalla muestra tu **API Key de producción una sola vez**: cópiala y guárdala antes de cerrar. Llamas a la API de producción en `https://api.mynexusapi.com`, con las mismas IP permitidas. > [!WARNING] > El paso a producción no se puede deshacer. El ambiente de pruebas sigue > funcionando: tu API Key de pruebas, tus bots de pruebas y el portal de pruebas > siguen activos con el saldo que te quede del paquete de pruebas. ## Estados de este flujo Los problemas del alta y de la carga del RUC aparecen junto al campo correspondiente; los de la API llegan con un `codEstado` en el cuerpo del error. Esta tabla reúne los dos. | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | Formulario | Falta el correo o el celular, o no tienen el formato esperado. | Corrige el dato en la pantalla "Crea tu cuenta". | | - | Formulario | Aparece "Escribe tus nombres solo con letras (de 2 a 100 caracteres)." o "Escribe tus apellidos solo con letras (de 2 a 100 caracteres)." | Escribe el dato solo con letras, espacios, apóstrofo, guion o punto, sin números ni otros signos. | | - | Formulario | Aparece "No pudimos validar la verificación de seguridad. Inténtalo de nuevo." | Resuelve la verificación de nuevo y pulsa **Continuar**. | | - | Formulario | Aparece "Ese celular ya tiene el máximo de cuentas. Usa otro número o escribe a soporte." porque el celular ya tiene 3 cuentas. | Usa otro celular o abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/). | | - | Formulario o pantalla | Aparece "Ya enviamos el máximo de códigos por hoy. Inténtalo mañana o escribe a soporte." | Espera 24 horas para pedir otro código o abre un ticket de soporte. | | - | Pantalla | Aparece "Ya enviamos el máximo de correos por hoy. Inténtalo mañana o escribe a soporte." | Busca en tu buzón el último correo "Crea tu clave de Ecuafact", que sigue sirviendo. Si no lo tienes, espera 24 horas o abre un ticket de soporte. | | - | Pantalla | Aparece "Espera 60 segundos para enviarlo de nuevo.", con los segundos que faltan. | Espera ese tiempo y pulsa de nuevo **Reenviar código** o **Reenviar correo**. | | - | Pantalla | Aparece "El código no coincide. Revisa el mensaje de WhatsApp." | Escribe de nuevo el código del último mensaje que recibiste. | | - | Pantalla | Aparece "Demasiados intentos con este código. Reenvía uno nuevo." o "El código venció. Reenvía uno nuevo." | Pulsa **Reenviar código** y usa el código nuevo. | | - | Pantalla | Aparece "No pudimos enviar el código por WhatsApp. Reenvíalo en un momento." o "No pudimos enviar el correo. Reenvíalo en un momento." | Espera 60 segundos y pulsa **Reenviar código** o **Reenviar correo**. | | - | Pantalla | Al crear la clave, el portal indica que no cumple la regla o que las dos claves no coinciden. | Escribe una clave de entre 8 y 128 caracteres, con letras y números, y repítela igual. El enlace sigue sirviendo. | | - | Pantalla | Aparece "Enlace usado o vencido" porque el enlace ya se usó, venció o pediste uno más reciente. | Si ya creaste tu clave, pulsa **Ingresar**; si no la recuerdas, usa **¿Olvidaste tu clave?** en la pantalla de ingreso. Si no, pulsa **Volver al registro** para recibir un enlace nuevo. | | - | Correo | Recibes "Ya tienes una cuenta de Ecuafact" en lugar del enlace para crear la clave. | Ingresa con tu correo y tu clave, o recupérala con **¿Olvidaste tu clave?**. | | - | Formulario | Al agregar el RUC aparece "El RUC debe tener 13 dígitos", falta la razón social o el certificado no se puede abrir. | Corrige el dato o el archivo en **Contribuyentes > Agregar RUC**. | | 3009 (`credenciales_invalidas`) | 401 | Llamas a la API con una API Key ausente o incorrecta. | Revisa `ECUAFACT_API_KEY` y que hayas copiado la clave completa. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está en **IP permitidas**, o la API no pudo identificar la IP de origen. En sandbox no ocurre por IP. | Revisa tu IP como se explica en [Si tu IP cambia en producción](#si-tu-ip-cambia). Si usas un proxy, llama directamente. Si persiste, abre un ticket con el valor de la cabecera `X-Correlation-Id`. | | 3011 (`acceso_denegado`) | 403 | Llamas con una identificación que no es la de tu sandbox, o con un tipo de comprobante que no está habilitado. | Usa la `identificacion` que devuelve `GET /v1/contexto`. | | 4004 (`cupo_agotado`) | 429 | Usaste los 3.000 documentos del paquete de pruebas. | Abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/); nuestro equipo de soporte amplía tu cupo. Volver a hacer el alta con el mismo RUC no repone los documentos usados. | El catálogo completo de códigos de la API está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Primeros pasos](/v1/guias/primeros-pasos): emite tu primera factura con la API Key que acabas de copiar. - [Datos de prueba](/v1/guias/datos-de-prueba): los casos que conviene probar antes de pasar a producción. - [Autenticación](/v1/guias/autenticacion): cómo viaja la API Key en cada petición y cómo se valida la IP. - [Ambientes y contribuyentes](/v1/guias/ambientes): qué cambia al pasar de pruebas a producción. --- # Datos de prueba Datos ficticios que usan todos los ejemplos y casos para provocar cada respuesta de la API antes de pasar a producción. Antes de pasar a producción te recomendamos comprobar que tu integración reacciona bien a cada respuesta posible: una factura autorizada, un reintento, un duplicado, un error de validación o un límite superado. Aquí tienes los datos ficticios que usan todos los ejemplos de la documentación, cómo conseguir una credencial de pruebas y, caso por caso, cómo provocar cada respuesta y qué debería hacer tu sistema con ella. Úsala como lista de verificación: si tu integración maneja bien todos los casos de las tablas, está lista para el [paso a producción](/v1/guias/ambientes#como-pasar-a-produccion). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Todo lo de esta página se ejecuta > contra `https://api-sandbox.mynexusapi.com`. Nunca uses RUC, cédulas, > certificados ni datos fiscales reales en ejemplos, capturas o tickets de > soporte. El certificado del RUC sí se carga en el Portal del Cliente para > firmar los comprobantes; no lo compartas fuera de ese formulario. ## URL base | Ambiente | URL base de la API | Portal del Cliente | |---|---|---| | Pruebas | `https://api-sandbox.mynexusapi.com` | `https://portal.mynexusapi.com` | | Producción | `https://api.mynexusapi.com` | `https://portal.mynexusapi.com` | Las diferencias entre los dos ambientes y cómo pasar de uno a otro están en [Ambientes y contribuyentes](/v1/guias/ambientes). ## Valores de ejemplo Todos los ejemplos de esta documentación usan estos valores. Son ficticios, así que si creaste tu propio sandbox, reemplaza la identificación y el RUC por los tuyos; los ves en la respuesta de `GET /v1/contexto`. | Dato | Valor | Dónde se usa | |---|---|---| | Identificación del emisor | `0123456789001` | En la ruta `/v1/contribuyentes/{identificacion}/...` y en `infoTributaria.ruc`. Es el RUC del emisor, de 13 dígitos. | | Establecimiento | `001` o `002` | En `infoTributaria.estab`. | | Punto de emisión | `001` | En `infoTributaria.ptoEmi`. | | Comprador con cédula | Tipo `05`, identificación `0123456789` | En `info.tipoIdentificacionComprador` e `info.identificacionComprador`. | | Comprador con RUC | Tipo `04`, identificación `0123456789001` | En los mismos campos que el anterior. | | Consumidor final | Tipo `07`, identificación `9999999999999` | Solo en facturas de hasta 50.00. | | `Idempotency-Key` | `FACTURA-2026-0001` | En la cabecera de la emisión. | | `idOperacion` | `3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f` | En `GET /v1/operaciones/{idOperacion}`. | | Clave de acceso de ejemplo | `0710202601012345678900110010010000001231234567811` | En la descarga del RIDE y del XML. Tiene 49 dígitos y un dígito verificador válido, pero no corresponde a ningún comprobante real. | ## El secuencial en pruebas El [secuencial](/v1/guias/glosario) es el número del comprobante dentro de su serie, que se forma con el establecimiento, el punto de emisión, el tipo de comprobante y el ambiente. Si quieres probar rápido, te recomendamos dejar que nosotros lo asignemos. | Qué envías en `infoTributaria.secuencial` | Qué pasa | |---|---| | Nada (omites el campo) | Asignamos el siguiente número libre de la serie. | | `"000000000"` (solo ceros) | Lo mismo que si lo omites: el número se asigna automáticamente. | | Un número de 1 a 999999999, solo dígitos y máximo 9 (por ejemplo `"124"` o `"000000124"`) | Se usa ese número. Si ya existe un comprobante autorizado o pendiente con ese número, la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`). | Esta regla es la misma en pruebas y en producción. Tampoco envíes `claveAcceso`: nosotros la asignamos y la recibes en el seguimiento o en el webhook. Si la envías, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`). ## Cómo obtener una credencial de pruebas Puedes obtenerla de dos maneras, según lo que necesites probar. | Camino | Para qué sirve | Cómo | |---|---|---| | Sandbox por autoservicio (recomendado) | Integrar tu sistema con tu propio RUC y tu certificado. | Crea tu cuenta en `https://portal.mynexusapi.com/sandbox`. Al terminar el alta, obtienes la API Key de pruebas en **Pruebas** del Portal del Cliente, donde se muestra una sola vez; el paso a paso está en [Sandbox de pruebas](/v1/guias/sandbox). | | Integración solicitada | Empresas que necesitan varios RUC o una configuración distinta. | Envía el [formulario de solicitud](https://www.ecuafact.com/) con tu RUC y tus IP de salida, como se explica en [Autenticación](/v1/guias/autenticacion#obten-tu-api-key). | Con una integración activa, puedes crear y rotar tus API Key en el Portal del Cliente, en **Cuenta > API Keys**, y administrar tus IP en **Cuenta > IP permitidas**. ## Casos de prueba Ejecuta estos casos antes de pasar a producción. Parte del archivo `comprobante.json` de [Primeros pasos](/v1/guias/primeros-pasos#paso-3.emite-la-factura) y cambia solo lo que indica la columna "Cómo provocarlo". Cada fila dice qué responde la API (el estado HTTP y el `codEstado` del cuerpo) y qué debería hacer tu sistema. Los errores traen además `msgError`, con la descripción del código, y `errores`, con el detalle. ### Emisión y admisión | Caso | Cómo provocarlo | Qué responde la API | Qué debe hacer tu sistema | |---|---|---|---| | Emisión exitosa | Envía `comprobante.json` sin cambios, con una `Idempotency-Key` nueva. | 202 con `estado` en `recibido`, el `codEstado` 1001 o 1002 y un `idOperacion`. | Guardar el `idOperacion` y seguir la operación; aceptar los dos códigos y tratar la `claveAcceso` como opcional. | | Reintento idempotente | Repite exactamente la misma petición, con la misma `Idempotency-Key` y el mismo cuerpo. | Un 202 con el mismo `idOperacion` y el estado actual de la operación. | Tratarlo como un éxito, sin crear otro registro. | | Conflicto de idempotencia | Repite la misma `Idempotency-Key`, pero cambia el cuerpo (por ejemplo `detalles[0].descripcion`). | 409 con el `codEstado` 3005 (`conflicto_idempotencia`). | No reintentar; para un comprobante nuevo, usar una clave nueva. | | Conflicto de referencia | Usa una `Idempotency-Key` nueva, deja la misma `referenciaExterna` y cambia el cuerpo. | 409 con el `codEstado` 3005 (`conflicto_idempotencia`). | Usar una `referenciaExterna` nueva para cada documento nuevo. | | Sin `Idempotency-Key` | Quita la cabecera `Idempotency-Key`. | 400 con el `codEstado` 3003 (`solicitud_invalida`); `errores` menciona la cabecera. | Corregir el cliente HTTP. | | JSON mal formado | Borra una coma o una llave de `comprobante.json`. | 400 con el `codEstado` 3003 (`solicitud_invalida`). | Corregir la serialización. | | Campo obligatorio ausente | Borra `origenReferencia`. | 422 con el `codEstado` 3002 (`comprobante_invalido`) y, en `errores`, `$.origenReferencia: Campo obligatorio.` | Corregir el dato y reenviar con la misma `Idempotency-Key`. | | Campo con formato inválido | Cambia `infoTributaria.estab` a `"0A1"`. | 422 con el `codEstado` 3002 (`comprobante_invalido`) y, en `errores`, `$.infoTributaria.estab: Solo se admiten digitos.` | Corregir el dato. | | Totales que no cuadran | Cambia `info.pagos[0].total` a 100.00 (el `importeTotal` es 115.00). | 422 con el `codEstado` 3002 (`comprobante_invalido`). | Recalcular los totales. Un 422 consume 1 documento como intento. | | Campo que no se envía | Agrega `"ambiente": "1"` dentro de `infoTributaria`. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | Quitar el campo, porque el ambiente lo define la URL. | | Consumidor final sobre el tope | Cambia el comprador al tipo `07` con `9999999999999`, sin cambiar el `importeTotal` de 115.00. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | Identificar al comprador cuando la factura supera 50.00. | | RUC de otro contribuyente | Cambia `infoTributaria.ruc` por un valor distinto de la identificación de la ruta (por ejemplo `1111111111001` o `0123456789002`). | 422 con el `codEstado` 3002 (`comprobante_invalido`) y, en `errores`, `$.infoTributaria.ruc: El RUC no corresponde al contribuyente del contexto.` | Usar en `infoTributaria.ruc` la misma `identificacion` de la ruta. | | Contribuyente no habilitado | Pide el RIDE con una identificación que no es tuya: `GET /v1/contribuyentes/0000000000001/comprobantes/0710202601012345678900110010010000001231234567811/ride`. | 403 con el `codEstado` 3011 (`acceso_denegado`). | Usar la `identificacion` del contexto. | | Duplicado | Emite con un `secuencial` explícito que no hayas usado (por ejemplo `"000000777"`) y espera a que se autorice. Luego envía otro comprobante con el mismo `secuencial`, una `Idempotency-Key` nueva y una `referenciaExterna` nueva. | 409 con el `codEstado` 3004 (`comprobante_duplicado`). | Omitir el `secuencial` o usar el siguiente número. | | XML con `codDoc` de otro tipo | Envía una factura en XML con `04` y `Content-Type: application/xml`. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | Corregir `codDoc` o usar la ruta del tipo correcto. | | Cuerpo demasiado grande | Envía una emisión de más de 2 MiB. | 413 con el `codEstado` 3006 (`cuerpo_excedido`). | Reducir el comprobante. | ### Acceso y límites | Caso | Cómo provocarlo | Qué responde la API | Qué debe hacer tu sistema | |---|---|---|---| | API Key inválida | Cambia un carácter de la API Key en `X-Api-Key`. | 401 con el `codEstado` 3009 (`credenciales_invalidas`). | No reintentar y revisar la configuración. | | IP no registrada | Llama desde otra red (por ejemplo, datos móviles) sin agregar esa IP. | 403 con el `codEstado` 3010 (`ip_no_autorizada`). | Registrar la IP en **Cuenta > IP permitidas**. | | Límite de solicitudes | Desde un sandbox, envía más de 60 consultas en un minuto (por ejemplo, `GET /v1/contexto` en un bucle sin espera). | 429 con el `codEstado` 5005 (`limite_solicitudes`) y la cabecera `Retry-After`. | Esperar los segundos que indica `Retry-After` y reducir la frecuencia. | | Cupo agotado | Ocurre cuando `disponibles` llega a 0 en `GET /v1/consumo`. No lo provoques gastando el cupo del sandbox. | 429 con el `codEstado` 4004 (`cupo_agotado`). | Ampliar el cupo como se explica en [Consumo y cuotas](/v1/guias/consumo) y no reintentar en bucle. | ### Resultado fiscal (seguimiento y webhooks) | Caso | Cómo provocarlo | Qué ves | Qué debe hacer tu sistema | |---|---|---|---| | Autorizado | Haz una emisión exitosa y síguela hasta el final. | `estado` en `autorizado` con el `codEstado` 2001 y el webhook `document.authorized`. | Marcar el documento como autorizado y descargar el RIDE. | | Rechazo del SRI | No hay un dato que garantice el rechazo en pruebas, porque depende de las validaciones del SRI. | `estado` en `rechazado` con el `codEstado` 3001 (`rechazo_sri`), el mensaje del SRI en `errores` y el webhook `document.rejected`. | Corregir y emitir de nuevo con un número nuevo, como se explica en [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). | | Comprobante no emitido | No se puede provocar a voluntad. | El webhook `document.failed`, con `estado` en `rechazado`, `rechazo_configuracion` o `error`, la causa en `codEstado` y el detalle en `errores`. | Actuar según el `codEstado`, como se explica en [Ciclo de vida](/v1/guias/ciclo-de-vida#estados-y-que-hacer). | | RIDE no disponible | Pide `/ride` con una `claveAcceso` válida que no emitiste (por ejemplo, la clave de ejemplo de esta página). | 404 con el `codEstado` 3013 (`no_encontrado`). | Comprobar la clave y esperar a que el comprobante esté autorizado. | | Clave de acceso inválida | Pide `/ride` con una clave de 49 dígitos a la que le cambiaste el último dígito. | 400 con el `codEstado` 3003 (`solicitud_invalida`). | Usar la `claveAcceso` del seguimiento sin modificarla. | El catálogo completo de códigos está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Primeros pasos](/v1/guias/primeros-pasos): el recorrido completo desde la API Key hasta el RIDE. - [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida): qué hacer con cada resultado fiscal. - [Errores](/v1/guias/errores): todos los códigos y si se reintentan o se corrigen. - [Ambientes y contribuyentes](/v1/guias/ambientes): la lista de verificación para pasar a producción. --- # Ciclo de vida del comprobante Un comprobante pasa de recibido a un resultado final, autorizado o no; aquí ves cada estado y qué hacer en él. Cuando nos envías un comprobante, te respondemos de inmediato con un identificador de operación y, a partir de ahí, nos encargamos de obtener su autorización ante el SRI. Esta página explica ese recorrido: qué significa cada valor de `estado`, qué indica el `codEstado` que lo acompaña y qué debe hacer tu sistema en cada caso. Te recomendamos leerla antes de programar el seguimiento o los webhooks. Al terminar sabrás cuándo un comprobante tiene validez fiscal, cuándo hay que esperar, cuándo corregir y cuándo no debes reenviar. ## Conceptos - **Recibido no es autorizado.** Cuando la API responde `202 Accepted`, el comprobante quedó **recibido**, pero todavía no tiene validez fiscal. Solo cuenta el resultado del SRI (Servicio de Rentas Internas, la autoridad tributaria de Ecuador), es decir, un `estado` en `autorizado`. - **Por qué es asíncrono.** El SRI puede tardar segundos o minutos en responder. Por eso no te hacemos esperar: te damos un `idOperacion` y puedes seguir la [operación](/v1/guias/glosario#operacion) por consulta o por webhook. - **Un estado y un código.** `estado` responde cómo va o cómo terminó la operación, y `codEstado`, un número de 4 dígitos cuyo primer dígito coincide con el `estado`, precisa el resultado y explica la causa cuando no terminó autorizada. Tu sistema decide con los dos. Todos los términos están en el [Glosario](/v1/guias/glosario). ## Cómo funciona El diagrama resume el recorrido de una emisión, desde el envío hasta el webhook con el resultado, y los pasos de abajo lo explican. ```mermaid sequenceDiagram participant S as Tu sistema participant P as Plataforma participant SRI S->>P: POST /facturas o la ruta de su tipo con Idempotency-Key alt Formato o totales inválidos P-->>S: 400 o 422, no se crea la operación else Comprobante válido P-->>S: 202 Accepted, estado recibido P->>SRI: Comprobante firmado SRI-->>P: Respuesta del SRI alt Autorizado P-)S: Webhook document.authorized else Rechazado por el SRI P-)S: Webhook document.rejected else No se pudo emitir P-)S: Webhook document.failed end end S->>P: GET /v1/operaciones/{idOperacion}, en cualquier momento P-->>S: 200 con estado, codEstado y errores ``` 1. **Envías** el comprobante a la ruta de su tipo, por ejemplo `POST /v1/contribuyentes/{identificacion}/facturas` para una factura, con la cabecera `Idempotency-Key`. Hay una ruta por tipo de documento: facturas, liquidaciones de compra, notas de crédito, notas de débito, guías de remisión y retenciones. El tipo lo fija la ruta, así que el cuerpo no incluye `infoTributaria.tipoDocumento`. Si el formato, la estructura o los totales fallan, recibes un 400 o un 422 y no se crea ninguna operación; el 400 no consume cupo y el 422 descuenta un documento como intento. 2. **Recibes `202 Accepted`** con `estado` en `recibido`, el `codEstado` 1001 o 1002, el `idOperacion` y `urlEstado`, la URL completa del seguimiento. Con 1001 la `claveAcceso` todavía es `null`, y con 1002 ya viene en la respuesta; tu sistema debe aceptar los dos casos. Si ya se conoce la autorización al responder, el 202 trae `autorizado` (2001). Si ya se conoce un rechazo definitivo, `rechazado` (3xxx) o `rechazo_configuracion` (4xxx), la respuesta es un `422` con el mismo cuerpo: `codEstado`, `msgError` y `errores`. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. 3. **Obtenemos el resultado del SRI.** Mientras no hay un resultado final, el `estado` sigue en `recibido`, con el `codEstado` 1001 o, cuando el comprobante ya tiene clave de acceso, 1002. El resultado puede tardar desde unos segundos hasta varios minutos, y no tienes que hacer nada para que avance. 4. **La operación llega a un estado final**: `autorizado` si el SRI lo autorizó, o `rechazado`, `rechazo_configuracion`, `error` o `cancelado` con un `codEstado` que explica la causa, la descripción del código en `msgError` y el detalle en `errores`. 5. **Te enteras del resultado** por [webhook](/v1/guias/webhooks), que se configura en el Portal del Cliente en **Integración > Eventos**, o por [seguimiento](/v1/guias/consulta-operacion) con `GET /v1/operaciones/{idOperacion}`. Te recomendamos usar el webhook como vía principal y la consulta como respaldo. ## Valores de `estado` | `estado` | Final | Qué significa | |---|---|---| | `recibido` | No | Recibimos el comprobante, pasó nuestras validaciones y todavía no tiene un resultado final. El `codEstado` es 1001 mientras no tiene clave de acceso y 1002 cuando ya la tiene. | | `autorizado` | Sí | El SRI autorizó el comprobante, que en producción tiene validez fiscal. `fhAutorizacion` puede venir `null`, porque algunas autorizaciones no traen fecha. | | `rechazado` | Sí | El comprobante no se autorizó por su contenido: lo rechazó el SRI, con el `codEstado` 3001 (`rechazo_sri`), o no cumplió una regla de la validación fiscal, con el 3002 (`comprobante_invalido`). | | `rechazo_configuracion` | Sí | No se pudo emitir porque falta o está mal una configuración del emisor: su configuración ante el SRI, la firma electrónica o el cupo. | | `error` | Sí | No se pudo emitir por un fallo inesperado o porque algo impidió de forma definitiva que se autorice. | | `cancelado` | Sí | La plataforma canceló el envío de forma automática. El comprobante no se emitió y no consumió cupo. | ## Estados y qué hacer Cada fila es un resultado que puedes ver en el seguimiento y en los webhooks. En la columna "Qué hacer", "claves nuevas" significa una `Idempotency-Key` nueva y una `referenciaExterna` nueva. | `estado` | `codEstado` | Webhook | Qué hacer | |---|---|---|---| | `recibido` | 1001 o 1002 | - o, si no pudimos confirmar a tiempo el resultado, el aviso `operation.requires_attention` | Espera el webhook o consulta de nuevo, cada 10 segundos al inicio y luego cada pocos minutos. No reenvíes. | | `autorizado` | 2001 | `document.authorized` | Marca el comprobante como autorizado, guarda la `claveAcceso` y descarga el [RIDE](/v1/guias/consulta-ride). | | `rechazado` | 3001 | `document.rejected` | Es un rechazo del SRI, y su mensaje viene en `errores`. Corrige el dato y emite **otro comprobante** con claves nuevas y el secuencial automático. Si reenvías el mismo número, la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`). | | `rechazado` | 3002 | `document.failed` | Corrige el dato que indica `errores` y reenvía con claves nuevas. Puedes conservar el número. | | `rechazo_configuracion` | 4001, 4002, 4003 o 4004 | `document.failed` | Corrige la configuración del emisor (su estado en **Cuenta > Contribuyentes**, la firma electrónica con **Reemplazar firma** en esa misma pantalla o el cupo, que repones comprando un paquete) y reenvía con claves nuevas y el mismo número. | | `error` | 5006 | `document.failed` | El comprobante no se creó. Reenvíalo con claves nuevas y el mismo número. | | `error` | 5007 o 5001 | `document.failed` | **No reemitas**, porque el comprobante podría existir. Búscalo en el seguimiento y escribe a soporte con el `idOperacion`. | | `cancelado` | 6001 | Ninguno; lo ves en el seguimiento | Reenvía con claves nuevas; puedes usar el mismo número. Con la misma `referenciaExterna` y el mismo cuerpo, la API devuelve la operación cancelada y no emite. | El significado de cada `codEstado` está en el [catálogo de Errores](/v1/guias/errores#codigos-de-resultado-de-una-operacion). Para conservar el número, envía el mismo `estab`, `ptoEmi` y `secuencial`. Si dejaste que te asignáramos el secuencial, lo encuentras en el `numeroDocumento` del seguimiento. Un reenvío con el mismo número puede responder con el mismo `idOperacion`. Si la operación terminó en `error` con el `codEstado` 5006, el reenvío usa el mismo documento y no descuenta otro; si corriges el contenido de un comprobante ya rechazado, el reenvío descuenta un documento, como se explica en [Consumo y cuotas](/v1/guias/consumo#cuando-se-reserva-consume-o-libera). > [!WARNING] > Ante un tiempo de espera agotado o un error de red en el `POST`, reintenta con > la **misma** `Idempotency-Key` y el mismo cuerpo. Cambiar la clave o la > `referenciaExterna` en ese momento puede emitir el comprobante dos veces. ## Ejemplo: lee una operación rechazada Este es el seguimiento de un comprobante que la validación fiscal rechazó antes de llegar al SRI, tal como lo devuelve `GET /v1/operaciones/{idOperacion}` con un `200 OK`: ```json { "estado": "rechazado", "codEstado": 3002, "msgError": "El comprobante no cumple las validaciones.", "errores": [ "identificacionComprador: El comprador no tiene identificacion." ], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "001-001-000000123", "referenciaExterna": "FAC-ERP-4581", "claveAcceso": null, "fhRecibido": "2026-11-09T10:15:00-05:00", "fhAutorizacion": null } ``` Para interpretarlo, sigue estos pasos: 1. Busca la fila de `rechazado` con el `codEstado` 3002 en [Estados y qué hacer](#estados-y-que-hacer). Es un estado final y el SRI no llegó a evaluar el comprobante. 2. Lee `errores`, que te dice qué dato corregir; `msgError` solo trae la descripción general del código. Muéstralos a quien revisa el comprobante, pero decide en tu código con `estado` y `codEstado`. 3. Corrige el comprobante y reenvíalo con claves nuevas. Si quieres conservar el número, envía el mismo `estab`, `ptoEmi` y `secuencial`. Los campos de esta respuesta se describen uno a uno en [Seguimiento de una operación](/v1/guias/consulta-operacion). El código para consultar en bucle con espera, en cURL, .NET, Python, Node.js, PHP y Java, está en [Primeros pasos, paso 4](/v1/guias/primeros-pasos#paso-4.sigue-la-operacion-hasta-la-autorizacion). ## Reintentos e idempotencia La `Idempotency-Key` identifica una intención de emitir. Con la misma clave y el mismo cuerpo, la API devuelve el mismo `idOperacion` y el estado actual de la operación, sin crear otro comprobante; con la misma clave y otro cuerpo, responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). La clave vale por integración (todas tus API Key) y ambiente, y se conserva 7 días. Rotar una API Key no reinicia la idempotencia. Guárdala junto con tu documento; puede ser, por ejemplo, tu número interno de factura o un UUID v4. Un 400 o un 422 no registra la clave, así que en ese caso corrige y reenvía con la misma. Para una emisión **nueva**, incluida la corrección de un rechazo o el reenvío de una operación `cancelado`, usa una clave nueva y una `referenciaExterna` nueva. La pareja `origenReferencia` + `referenciaExterna` también identifica la intención, de modo que con la misma referencia y otro cuerpo la API responde 409 con el `codEstado` 3005. Tienes más recomendaciones en [Buenas prácticas](/v1/guias/buenas-practicas). ## Cupo Cada etapa del ciclo afecta al cupo de documentos de una manera distinta: | Momento | Consume cupo | |---|---| | Respuesta 400 | No. | | Respuesta 422 | Sí; descuenta un documento como intento. | | `202 Accepted` | Aparta un documento de tu saldo (`reservados`) mientras no hay resultado. | | Autorizado por el SRI | Sí; el documento apartado pasa a consumido. | | `rechazado`, con el `codEstado` 3001 o 3002 | Sí. | | `rechazo_configuracion` | Sí. | | `error`, con el `codEstado` 5006 o 5007 | No; el documento sigue apartado y lo usa el reenvío con el mismo número. | | `cancelado` | No; el documento apartado se libera. | | Reenvío de un comprobante rechazado con el mismo contenido | No descuenta un documento adicional. | | Reenvío de un comprobante rechazado con el contenido corregido | Sí; es un envío nuevo. | Tu saldo se consulta como se explica en [Consumo y cuotas](/v1/guias/consumo). ## Errores frecuentes | Error | Por qué pasa | Cómo evitarlo | |---|---|---| | Marcar como facturado al recibir el 202 | El 202 solo confirma la recepción. | Espera a que el `estado` sea `autorizado` o a recibir el webhook `document.authorized`. | | Consultar el estado en un bucle sin espera | Agota tu límite de solicitudes y la API responde 429 con el `codEstado` 5005 (`limite_solicitudes`). | Espera 10 segundos entre consultas y usa webhooks. | | Reenviar con otra `Idempotency-Key` ante un timeout | Crea una segunda emisión. | Reintenta con la misma clave y el mismo cuerpo. | | Reenviar el mismo número tras un rechazo del SRI | La API responde 409 con el `codEstado` 3004. | Emite con el secuencial automático. | | Reemitir ante el `codEstado` 5007 (`resultado_no_confirmado`) | El comprobante podría existir y lo duplicarías. | No reemitas. Búscalo en el seguimiento y escribe a soporte con el `idOperacion`. | | Decidir con `msgError` o `errores` | Son textos legibles que pueden cambiar. | Decide con `estado` y `codEstado`, y usa `msgError` y `errores` solo para mostrarlos o registrarlos. | ## Siguientes pasos - [Seguimiento de una operación](/v1/guias/consulta-operacion): todos los campos de `GET /v1/operaciones/{idOperacion}`. - [Webhooks](/v1/guias/webhooks): recibe `document.authorized`, `document.rejected` y `document.failed` sin consultar en bucle. - [Primeros pasos](/v1/guias/primeros-pasos): recorre el ciclo completo con una factura de prueba. - [Errores](/v1/guias/errores#catalogo-de-codestado): qué significa cada `codEstado` y si se reintenta o se corrige. --- # Autenticación Cada petición a la API lleva tu API Key en la cabecera `X-Api-Key`. En producción, además, debe salir de una IP registrada para tu integración. Puedes llamar a nuestra API sin iniciar sesión ni renovar tokens. Cada petición se autentica por sí sola con dos comprobaciones: que traiga una API Key válida y, en producción, que llegue desde una IP pública que registraste para tu integración. En el sandbox se acepta cualquier IP. Cada ambiente usa su propia API Key. En esta página verás cómo enviar la API Key, cómo obtenerla, guardarla y rotarla, cómo averiguar y registrar tu IP de salida y qué significa cada error de autenticación. Al terminar tendrás una llamada a `GET /v1/contexto` que responde 200. ## Conceptos - **API Key.** Es la credencial de tu integración. Una sola API Key cubre todos los [contribuyentes](/v1/guias/glosario#contribuyente) y tipos de comprobante habilitados para tu integración, y dentro de la API no existen usuarios ni permisos por persona. Más detalle en [API Key](/v1/guias/glosario#api-key). - **IP permitida.** Es la dirección IP pública desde la que tu servidor sale a Internet. En producción, la API solo acepta tu API Key si la petición llega desde una IP registrada. Las IP se registran por integración, así que valen para todas tus API Key. El sandbox no exige IP registrada. - **Ambiente.** Pruebas y producción tienen URL distintas y cada uno tiene sus propias API Key. Las diferencias están en [Ambientes y contribuyentes](/v1/guias/ambientes). Si la API Key falta, no existe, está revocada o venció, la respuesta es un 401 con el `codEstado` 3009 (`credenciales_invalidas`). En producción, si la API Key es válida pero la IP no está permitida, la respuesta es un 403 con el `codEstado` 3010 (`ip_no_autorizada`). Revisa la causa que corresponda en [Errores de autenticación](#errores-de-autenticacion). ## Antes de empezar - [ ] Una API Key de pruebas. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); la API Key la obtienes después, en **Pruebas** del Portal del Cliente. - [ ] La IP pública de salida de tu servidor, registrada en el Portal del Cliente como se explica en [Registra tu IP](#registra-tu-ip). Solo se exige en producción; el sandbox acepta cualquier IP. - [ ] La API Key guardada en la variable de entorno `ECUAFACT_API_KEY`, como se explica en [Guarda la API Key](#guarda-la-api-key). ## Envía la API Key Incluye la cabecera `X-Api-Key` en **cada** petición a `/v1`. | Cabecera | Obligatoria | Valor | |---|---|---| | `X-Api-Key` | Sí | Tu API Key completa, tal como la copiaste del portal al crearla. Tiene dos partes separadas por un punto (`prefijo.secreto`). | El ejemplo consulta `GET /v1/contexto`, que es la llamada más simple para comprobar que tu API Key y tu IP funcionan. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/contexto" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/contexto"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/contexto", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contexto")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```bash-cli # Una sola vez: guarda tu API Key de pruebas en el CLI (te la pide sin mostrarla). ecuafact login --entorno sandbox # Resultado esperado: tu integración y sus contribuyentes, en tabla. ecuafact cuenta --entorno sandbox ``` ### Resultado esperado Si la API Key y la IP son correctas, recibes `200 OK` con tu integración y tus contribuyentes: ```json { "idCliente": "1f2e3d4c-5b6a-4789-9012-abcdef012345", "nombre": "Integracion de ejemplo", "contribuyentes": [ { "identificacion": "0123456789001", "puedeEmitir": true, "puedeRecibir": true, "tiposComprobante": [ "01", "03", "04", "05", "06", "07" ], "marcaBlanca": false } ] } ``` | Campo | Tipo | Descripción | |---|---|---| | `idCliente` | string (UUID) | Identificador de tu integración. Inclúyelo al pedir soporte. | | `nombre` | string | Nombre de tu integración. | | `contribuyentes` | array | Contribuyentes habilitados para tu API Key en este ambiente. Puede venir vacío si aún no tienes ninguno habilitado. | | `contribuyentes[].identificacion` | string | Identificación completa del contribuyente (para un RUC, sus 13 dígitos). Es el valor que usas en la ruta `{identificacion}` y en `infoTributaria.ruc`. | | `contribuyentes[].puedeEmitir` | boolean | `true` si puedes emitir comprobantes para este contribuyente. | | `contribuyentes[].puedeRecibir` | boolean | Indica si el contribuyente tiene habilitada la recepción. | | `contribuyentes[].tiposComprobante` | array de string | Tipos de comprobante habilitados (`tipoDocumento`): `01`, `03`, `04`, `05`, `06`, `07`. | | `contribuyentes[].marcaBlanca` | boolean | `true` si el contribuyente es de marca blanca y sus comprobantes no tienen RIDE. Más detalle en [Contexto](/v1/guias/consulta-contexto). | Sabes que funcionó cuando el estado HTTP es 200 y ves tus contribuyentes. Si recibes un 401 con el `codEstado` 3009 (`credenciales_invalidas`) o un 403 con el `codEstado` 3010 (`ip_no_autorizada`), revisa [Errores de autenticación](#errores-de-autenticacion). ## Obtén tu API Key Puedes conseguir una API Key de distintas maneras, según si quieres probar, si ya tienes acceso al portal o si vas a producción. | Situación | Cómo la obtienes | |---|---| | Quieres probar y no tienes cuenta | [Crea tu cuenta](/v1/guias/sandbox) en `https://portal.mynexusapi.com/sandbox`. Al terminar el alta, ingresa al portal y sigue la fila siguiente. | | Tu cuenta está en pruebas | Abre **Pruebas** en el Portal del Cliente y pulsa **Generar** en "API Key de pruebas" (si ya tienes una, pulsa **Rotar**). La API Key se muestra una sola vez. | | Necesitas producción | Desde el Portal del Cliente, en **Pasar a producción**, como se explica en [Sandbox de pruebas](/v1/guias/sandbox#pasar-a-produccion). La API Key de producción se muestra una sola vez. | | Ya estás en producción | Entra a **Cuenta > API Keys** y pulsa **Crear API Key**. Escribe un nombre que identifique su uso, por ejemplo `ERP produccion`. | Al crear una clave en el portal, la API Key completa **se muestra una sola vez**, así que cópiala en ese momento a tu gestor de secretos. Si la pierdes, no se puede recuperar; en ese caso, crea otra y revoca la anterior. ### Scopes y RUC de una API Key Cada API Key tiene dos límites independientes: - **Scopes:** qué acciones puede hacer. - **RUC permitidos:** sobre qué contribuyentes puede actuar. Una API Key con `*` en scopes puede usar todos los servicios; una API Key con una lista solo puede usar esos servicios. Lo mismo aplica a `ruc`: `*` significa todos los RUC y una lista limita la API Key a esas identificaciones. La clave que se crea con un sandbox queda limitada a su RUC y a los scopes de integración; no puede emitir ni consultar otro contribuyente. En el Portal del Cliente, al crear una clave en **Cuenta > API Keys**, eliges los servicios y los RUC, y la tabla de claves muestra el alcance de cada una. Si no limitas ninguno, la clave puede usar todos los servicios y todos los RUC. Para cambiar los permisos de una clave existente, crea una nueva y revoca la anterior. Los scopes disponibles son: | Scope | Permite | |---|---| | `cuenta:leer` | Consultar el contexto y el consumo. | | `comprobantes:leer` | Consultar operaciones y comprobantes emitidos, y descargar el RIDE y el XML. | | `comprobantes:emitir` | Emitir y validar comprobantes. | | `sri:consultar` | Consultar contribuyentes, establecimientos, identificaciones y claves de acceso. | | `perfil:leer` | Ver el perfil del emisor. | | `perfil:escribir` | Actualizar el perfil del emisor y su logo. | | `webhooks:leer` | Ver destinos, entregas e intentos. | | `webhooks:gestionar` | Crear, editar, rotar secreto, pausar, reanudar y deshabilitar destinos. | | `webhooks:probar` | Enviar el evento de prueba. | | `webhooks:reintentar` | Reenviar una entrega. | Una API Key limitada a un RUC no puede ver ni administrar destinos de otro RUC ni un destino para todos los RUC. Si intentas una operación fuera de su alcance, la API responde 403 con el `codEstado` 3011 (`acceso_denegado`). > [!WARNING] > La API Key permite emitir comprobantes a nombre de tus contribuyentes. No la > pegues en tickets, chats, repositorios ni capturas de pantalla. ## Guarda la API Key Te recomendamos que tu código lea la API Key desde fuera del código fuente. Todos los ejemplos de esta documentación la leen de la variable de entorno `ECUAFACT_API_KEY`, y la tabla muestra cómo definirla según dónde corre tu aplicación. | Dónde | Cómo | |---|---| | Tu equipo (desarrollo) | Define la variable en la sesión: `export ECUAFACT_API_KEY="..."` (Linux/macOS) o `$env:ECUAFACT_API_KEY="..."` (PowerShell). Si usas un archivo `.env`, agrégalo a `.gitignore`. | | Servidor o contenedor | Define una variable de entorno del servicio (systemd, Docker, Kubernetes Secret o la configuración de la aplicación en tu proveedor de nube). | | Producción | Usa un gestor de secretos que inyecte el valor al iniciar la aplicación, por ejemplo Azure Key Vault, AWS Secrets Manager, Google Secret Manager o HashiCorp Vault. | | .NET en desarrollo | Ejecuta `dotnet user-secrets set "Ecuafact:ApiKey" "..."` y léela desde la configuración. | Además, te recomendamos estas tres prácticas: - Usa la API Key **solo en tu backend**. Nunca la pongas en el navegador, en una app móvil ni en una aplicación de escritorio que entregues a terceros, porque cualquiera podría extraerla. - No la escribas en logs. Si registras cabeceras, enmascara `X-Api-Key`. - Usa una API Key distinta por sistema, por ejemplo una para el ERP y otra para la tienda en línea. Así puedes revocar una sin detener la otra. ## Rota o revoca una API Key Rota la API Key si se filtró, si una persona con acceso deja el equipo o cuando lo pida tu política de seguridad. La rotación no corta el servicio si sigues este orden: 1. En el portal, entra a **Cuenta > API Keys**, pulsa **Crear API Key** y copia la nueva API Key. 2. Actualiza el secreto en tu servidor y reinicia o recarga la aplicación. 3. Verifica con `GET /v1/contexto` que la nueva API Key responde 200. 4. En **Cuenta > API Keys**, abre el menú de la clave anterior y pulsa **Revocar**. La revocación tarda hasta 30 segundos en aplicarse. Pasado ese tiempo, la clave revocada recibe un 401 con el `codEstado` 3009 (`credenciales_invalidas`). > [!WARNING] > Si sospechas que tu API Key se filtró, revócala de inmediato aunque tu servicio > se detenga unos minutos. Quien la tenga podría emitir comprobantes con validez > fiscal si también controla una IP registrada. ## Registra tu IP En producción, puedes registrar en la lista de **IP permitidas** de tu integración las IP desde las que llamas a la API. Si una petición llega desde una IP que no está en la lista, la API la rechaza con un 403 y el `codEstado` 3010 (`ip_no_autorizada`), aunque la API Key sea correcta. El sandbox no exige IP registrada. ### Averigua tu IP pública de salida La IP que importa es la que ve la API, no la de tu red interna. Las direcciones que empiezan por 192.168, 10 o 172.16 a 172.31 son privadas y nunca llegan a la API. Para conocer la IP pública, ejecuta este comando **desde el mismo servidor** que llamará a la API: ```bash curl -4 https://ifconfig.me # IP publica IPv4 curl -6 https://ifconfig.me # IP publica IPv6 (si tu servidor tiene IPv6) ``` | Tu caso | Qué IP registrar | |---|---| | Servidor propio con IP fija | La IP pública fija que te asignó tu proveedor de Internet. | | Oficina o red con NAT | La IP pública del router o firewall por el que sale el tráfico. Todos los equipos detrás del NAT comparten esa IP. | | Nube (máquina virtual) | Asigna una IP pública estática (IP elástica o reservada). La IP dinámica por defecto puede cambiar al reiniciar. | | Nube (funciones, contenedores administrados, PaaS) | Estos servicios salen por IP que cambian. Configura una salida fija (NAT gateway con IP estática o la opción de IP de salida dedicada de tu proveedor) y registra esa IP. | | Tu equipo de desarrollo (casa u oficina) | La IP pública de tu conexión. Suele cambiar, así que vuelve a revisarla si empiezas a recibir el `codEstado` 3010 (`ip_no_autorizada`). | ### Formatos admitidos Para registrar una IP, entra en el Portal del Cliente a **Cuenta > IP permitidas** y pulsa **Agregar**. Para borrar una IP que ya no usas, pulsa **Quitar**. La tabla muestra qué formatos acepta la lista. | Formato | Ejemplo | Admitido | |---|---|---| | IPv4 exacta | `203.0.113.10` | Sí | | IPv6 exacta | `2001:db8::10` | Sí | | Rango IPv4 en notación CIDR | `203.0.113.0/24` | Sí | | Rango IPv6 en notación CIDR | `2001:db8::/64` | Sí, con prefijo de /32 o más largo. | | Cualquier dirección (`0.0.0.0/0` o `::/0`) | `0.0.0.0/0` | No | | Nombre de dominio | `servidor.midominio.com` | No | Si no registras ninguna IP, en producción solo funcionan las API Key limitadas a servicios y RUC concretos (no a todos). En cuanto registras una IP, la lista se aplica a todas tus API Key. Usa **Probar** en la misma pantalla para comprobar si una IP queda cubierta por tu lista. Registra solo las IP que de verdad llaman a la API, porque cada IP o rango que agregas es un punto de entrada más para tu API Key. > [!NOTE] > Si tu servidor tiene IPv4 e IPv6, la conexión puede salir por cualquiera de las > dos. Registra ambas, o fuerza IPv4 en tu cliente HTTP (por ejemplo `curl -4`). La API valida la IP de la conexión que recibe, así que enviar cabeceras como `X-Forwarded-For` no cambia la IP que se valida. ## Límite de intentos fallidos Para proteger tu API Key de quien intenta adivinarla, limitamos **por IP de origen** los intentos de autenticación fallidos, es decir, las peticiones rechazadas con un 401 y el `codEstado` 3009 (`credenciales_invalidas`) o con un 403 y el `codEstado` 3010 (`ip_no_autorizada`). | Regla | Valor | |---|---| | Intentos fallidos permitidos | 20 por minuto, por IP. En IPv6 se cuentan juntas todas las direcciones del mismo prefijo /64. | | Ventana | El minuto de reloj, de hh:mm:00 a hh:mm:59. El contador vuelve a cero al empezar el minuto siguiente. | | Al superar el límite | Toda petición desde esa IP recibe un 429 con el `codEstado` 5005 (`limite_solicitudes`) hasta que termine el minuto, **sin importar qué API Key envíe**, aunque sea correcta. | | Cuánto esperar | Los segundos que indica la cabecera `Retry-After`. | | Reinicio | El contador no se reinicia con una autenticación correcta: expira al terminar el minuto. | Un bucle que reintenta con una API Key equivocada termina bloqueando tu propia IP. Si recibes el `codEstado` 3009 (`credenciales_invalidas`) o el 3010 (`ip_no_autorizada`), corrige la causa antes de reintentar. El detalle de los límites está en [Límite de request](/v1/guias/limite-de-request). ## Errores de autenticación | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 3009 (`credenciales_invalidas`) | 401 | Falta la cabecera `X-Api-Key`, está mal escrita o la API Key no existe, está revocada, venció o pertenece a otro ambiente. | Revisa el nombre de la cabecera y que copiaste la API Key completa, con el punto. Si la revocaste, crea otra. Si es de otro ambiente, usa la clave que corresponde a la URL. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la API Key es válida pero la petición llega desde una IP que no está en **IP permitidas**, o la API no pudo identificar la IP de origen. En sandbox no ocurre por IP. | Averigua tu IP pública de salida y agrégala en **Cuenta > IP permitidas**. Si usas un proxy, llama directo a la URL de la API. Si persiste, abre un ticket con el valor de `X-Correlation-Id`. | | 3011 (`acceso_denegado`) | 403 | La autenticación fue correcta, pero el contribuyente de la ruta o el tipo de comprobante no están habilitados. | Revisa `GET /v1/contexto` y usa una `identificacion` y un `tipoDocumento` que aparezcan ahí; la misma `identificacion` va en `infoTributaria.ruc`. | | 5005 (`limite_solicitudes`) | 429 | Superaste 20 intentos fallidos por minuto desde la misma IP, o el límite de solicitudes por minuto de tu integración. | Espera los segundos que indica `Retry-After` y corrige la API Key o la IP antes de reintentar. | ### Cuándo aparece 3009 | Caso | Qué revisar | |---|---| | No enviaste `X-Api-Key` | La cabecera debe viajar en todas las peticiones a `/v1`. | | La clave está mal formada | Debe tener las dos partes separadas por un punto (`prefijo.secreto`), sin espacios ni saltos de línea. Vuelve a copiarla desde **Cuenta > API Keys**. | | La clave fue revocada, venció o se eliminó | En **Cuenta > API Keys** la clave aparece como **Revocada** o **Vencida**. Crea una nueva. | | La clave pertenece a otro ambiente | Pruebas y producción usan claves distintas. Usa la clave del ambiente de la URL. | | La clave no existe | Revisa que hayas copiado la clave completa y que estés usando la integración correcta. | La IP no se informa con 3009. En producción, si la clave es válida y la IP no está permitida, la respuesta es 403 con el `codEstado` 3010 (`ip_no_autorizada`). El sandbox no exige IP registrada. ### Cuándo aparece 3010 | Caso | Qué revisar | |---|---| | La IP no está en **IP permitidas** | Averigua tu IP pública de salida y agrégala en **Cuenta > IP permitidas**. | | La IP cambió por VPN, nube o proxy | Registra la IP de salida real o fuerza una salida fija. | | La API no pudo identificar la IP | Llama directo a la URL de la API, sin proxies que oculten el origen. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). Si el problema persiste, abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/). También puedes consultar el [centro de ayuda](https://ecuafact.com/ayuda/) o escribir por [WhatsApp](https://wa.me/593988315544). Horario: lunes a viernes, 09:00-18:00 GMT-5. Primera respuesta: 1 día hábil; producción caída: 4 horas. ## Siguientes pasos - [Ambientes y contribuyentes](/v1/guias/ambientes): elige la URL correcta y la `identificacion` que usarás en las rutas. - [Primeros pasos](/v1/guias/primeros-pasos): emite tu primer comprobante en pruebas. - [Límite de request](/v1/guias/limite-de-request): cuántas solicitudes por minuto puedes hacer y cómo leer `Retry-After`. - [Errores](/v1/guias/errores): todos los códigos y qué hacer ante cada uno. --- # Límite de request La API limita cuántas solicitudes por minuto hace cada integración (200 por defecto, 60 en un sandbox) y los intentos fallidos por IP. Para que nuestros servicios respondan rápido a todos nuestros clientes, limitamos cuántas solicitudes puede hacer cada integración por minuto y cuántos intentos de autenticación fallidos aceptamos desde una misma IP. Si superas un límite, la API rechaza la petición con un 429 y te dice cuántos segundos esperar antes de reintentar. En esta página verás qué se limita y con qué valores, qué cabeceras te informan cuánto te queda, cómo leerlas en tu código y cómo organizar tus llamadas para no llegar nunca al límite. ## Conceptos Un **límite de solicitudes** (en inglés, *rate limit*) fija cuántas peticiones puedes hacer en una ventana de tiempo; las que pasan del máximo se rechazan y puedes repetirlas después de esperar. No tiene relación con cuántos comprobantes puedes emitir, que es lo que mide el [cupo](/v1/guias/glosario#cupo) y se explica en [Consumo y cuotas](/v1/guias/consumo). | Concepto | Qué limita | Respuesta al superarlo | |---|---|---| | Límite de solicitudes | Las peticiones por minuto, a cualquier endpoint. | 429 con el `codEstado` 5005 (`limite_solicitudes`). | | Cupo de documentos | Los comprobantes que puedes emitir con tus paquetes vigentes. | 429 con el `codEstado` 4004 (`cupo_agotado`). | Como los dos responden con el mismo estado HTTP, distínguelos siempre por el `codEstado` del cuerpo: el primero se resuelve esperando y el segundo no. ## Qué se limita | Límite | Valor | Se cuenta por | Qué peticiones cuentan | |---|---|---|---| | Solicitudes | 200 por minuto por defecto y 60 por minuto en un sandbox. | Por integración: todas tus API Key comparten el mismo contador. | Toda petición a `/v1` que pasa la autenticación, cualquiera sea su resultado (éxito o error). | | Intentos de autenticación fallidos | 20 por minuto. | Por IP de origen (en IPv6, por prefijo /64). | Solo las peticiones rechazadas con un 401 y el `codEstado` 3009 (`credenciales_invalidas`), o con un 403 y el `codEstado` 3010 (`ip_no_autorizada`). | Los dos contadores funcionan con una **ventana fija de un minuto de reloj**: cada uno vale para el minuto en curso, de hh:mm:00 a hh:mm:59, y vuelve a cero al empezar el siguiente. No es una ventana móvil, así que si gastas las 200 solicitudes en los primeros 10 segundos, tienes que esperar los 50 restantes. El límite de **solicitudes por integración** vale 200 por minuto salvo que tu integración tenga otro valor configurado; un [sandbox](/v1/guias/sandbox) se crea con 60. El valor que se aplica a ti es siempre el que devuelve la cabecera `X-RateLimit-Limit`. El límite de **intentos fallidos por IP** protege tu cuenta de quien intenta adivinar una API Key. Cuando una IP acumula 20 fallos en el minuto, las peticiones desde esa IP reciben un 429 hasta que termine el minuto, aunque traigan una API Key correcta y cambies de clave. Una autenticación correcta no reinicia el contador: expira al terminar el minuto. El detalle está en [Autenticación](/v1/guias/autenticacion#limite-de-intentos-fallidos). ## Qué pasa al superar el límite La API rechaza la petición que excede el límite y no la procesa: no se emite nada, así que puedes repetirla tal cual cuando termine la espera. | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto de tu integración. | Espera los segundos que indica `Retry-After` y reintenta. Si es una emisión, usa la misma `Idempotency-Key`. | | 5005 (`limite_solicitudes`) | 429 | Tu IP acumuló 20 intentos de autenticación fallidos en el minuto. | Corrige la API Key o registra la IP, y espera lo que indica `Retry-After` antes de reintentar. | El cuerpo de la respuesta es el de cualquier error de la API: ```json { "estado": "error", "codEstado": 5005, "msgError": "Límite de solicitudes excedido.", "errores": [] } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | Siempre `error` para este límite. | | `codEstado` | integer | Siempre 5005 para este límite. | | `msgError` | string | Texto fijo del código. | | `errores` | array de string | En este código siempre viene vacío. | ## Cabeceras de la respuesta | Cabecera | Cuándo aparece | Significado | |---|---|---| | `X-RateLimit-Limit` | En las respuestas a peticiones autenticadas, cuando tu integración tiene un límite configurado. También en el 429 por intentos fallidos, donde vale 20. | El máximo de solicitudes en la ventana de un minuto. | | `X-RateLimit-Remaining` | Junto con `X-RateLimit-Limit`. | Las solicitudes que te quedan en el minuto en curso, sin contar esta. | | `X-RateLimit-Reset` | Solo en el 429 con el `codEstado` 5005 (`limite_solicitudes`). | El momento en que se reinicia la ventana, en segundos Unix (epoch). | | `Retry-After` | En todas las respuestas 429 y 503. | Los segundos que debes esperar antes de reintentar. | Una respuesta 401 no trae las cabeceras del límite: la petición no llegó a identificar tu integración, así que no hay un contador que informar. Así se ve una respuesta normal: ``` HTTP/1.1 200 OK X-RateLimit-Limit: 200 X-RateLimit-Remaining: 42 ``` Y así, una respuesta al superar el límite: ``` HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 200 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1757341500 Retry-After: 43 Content-Type: application/json { "estado": "error", "codEstado": 5005, "msgError": "Límite de solicitudes excedido.", "errores": [] } ``` ### Lee las cabeceras en tu código Los ejemplos llaman a `GET /v1/contexto` e imprimen el estado HTTP y las cabeceras del límite. Las cabeceras vienen en todas las respuestas autenticadas, así que puedes leerlas de la misma forma en cualquier otra petición. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```bash curl -s -o /dev/null -D - "https://api-sandbox.mynexusapi.com/v1/contexto" \ -H "X-Api-Key: $ECUAFACT_API_KEY" | grep -i -E "^HTTP|x-ratelimit|retry-after" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/contexto"); string Cabecera(string nombre) => respuesta.Headers.TryGetValues(nombre, out var valores) ? string.Join(",", valores) : "(no viene)"; Console.WriteLine($"HTTP {(int)respuesta.StatusCode}"); Console.WriteLine($"X-RateLimit-Limit: {Cabecera("X-RateLimit-Limit")}"); Console.WriteLine($"X-RateLimit-Remaining: {Cabecera("X-RateLimit-Remaining")}"); Console.WriteLine($"Retry-After: {Cabecera("Retry-After")}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/contexto", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print("HTTP", r.status_code) for nombre in ("X-RateLimit-Limit", "X-RateLimit-Remaining", "Retry-After"): print(f"{nombre}: {r.headers.get(nombre, '(no viene)')}") ``` ```javascript // Node.js 18 o superior. Guarda como limite.mjs y ejecuta: node limite.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log('HTTP', res.status); for (const nombre of ['X-RateLimit-Limit', 'X-RateLimit-Remaining', 'Retry-After']) { console.log(`${nombre}: ${res.headers.get(nombre) ?? '(no viene)'}`); } ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], CURLOPT_HEADERFUNCTION => function ($ch, $linea) use (&$cabeceras) { $partes = explode(':', $linea, 2); if (count($partes) === 2) { $cabeceras[strtolower(trim($partes[0]))] = trim($partes[1]); } return strlen($linea); }, ]); curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo 'HTTP ' . $estado . PHP_EOL; foreach (['x-ratelimit-limit', 'x-ratelimit-remaining', 'retry-after'] as $nombre) { echo $nombre . ': ' . ($cabeceras[$nombre] ?? '(no viene)') . PHP_EOL; } ``` **Resultado esperado.** Con una API Key de sandbox, el estado es 200, `X-RateLimit-Limit` vale 60, `X-RateLimit-Remaining` muestra las solicitudes que te quedan en el minuto (por ejemplo 59) y `Retry-After` no aparece. Si ejecutas el ejemplo más de 60 veces en el mismo minuto, verás un 429, con `X-RateLimit-Remaining` en 0 y `Retry-After` con los segundos que faltan. El valor de `Retry-After` depende de la respuesta: | Respuesta | Valor de `Retry-After` | |---|---| | 429 con el `codEstado` 5005 (`limite_solicitudes`) | Los segundos que faltan para que termine el minuto en curso, de 1 a 60. | | 429 con el `codEstado` 4004 (`cupo_agotado`) | 60. Esperar no repone el cupo; revisa [Consumo y cuotas](/v1/guias/consumo). | | 503 con el `codEstado` 5002 (`servicio_no_disponible`) | 5. | ## Cómo respetar el límite en tu código Cuando una respuesta te avisa que llegaste al límite, sigue estos pasos: 1. Lee `X-RateLimit-Remaining` en cada respuesta. Si llega a 0, no hagas la siguiente petición hasta el momento que indica `X-RateLimit-Reset`. 2. Si recibes un 429 con el `codEstado` 5005 (`limite_solicitudes`), espera **al menos** los segundos que indica `Retry-After` y reintenta la misma petición. Si es una emisión, reenvía la misma `Idempotency-Key` con el mismo cuerpo, para que no se emita dos veces. 3. Si recibes un 429 con el `codEstado` 4004 (`cupo_agotado`), no reintentes en bucle: el cupo no se repone solo y hay que ampliarlo. Además, organiza tus llamadas para no llegar al límite: - Usa los [webhooks](/v1/guias/webhooks) para enterarte del resultado de tus emisiones. Consultar `GET /v1/operaciones/{idOperacion}` cada segundo gasta tu límite sin necesidad. - En procesos masivos, reparte las emisiones a lo largo del minuto (por ejemplo, 3 por segundo en lugar de 200 de golpe) y limita cuántas peticiones haces al mismo tiempo. En [Buenas prácticas](/v1/guias/buenas-practicas#reintentos-con-espera-exponencial) tienes un ejemplo de reintentos con espera exponencial y variación aleatoria (*jitter*) en varios lenguajes. Si tu volumen necesita más de 200 solicitudes por minuto de forma sostenida, puedes solicitar un límite mayor para tu integración por el canal comercial. ## Si usas un SDK o el CLI Si te integras con nuestros [SDK oficiales](/v1/guias/sdk) o con nuestro [CLI de Ecuafact](/v1/guias/cli), puedes dejarles buena parte de este trabajo. La tabla muestra qué hacen ante cada caso y qué te queda por hacer a ti. | Herramienta | Ante un 429 con el `codEstado` 5005 (`limite_solicitudes`) | Ante un 429 con el `codEstado` 4004 (`cupo_agotado`) | |---|---|---| | SDK | Por defecto espera lo que indica `Retry-After` y reintenta solo. Si desactivas la opción `RetryRateLimited`, lanza una excepción de límite que trae los segundos de espera sugeridos. | Nunca reintenta: lanza una excepción de cupo. | | CLI | Espera lo que indica `Retry-After` y reintenta solo. Además, cuando una respuesta le indica que ya no te quedan solicitudes en el minuto, espera al minuto siguiente antes de enviar la próxima y te avisa en la terminal cuántos segundos faltan. Así, en un lote grande casi nunca llega a recibir un 429. | No reintenta. El comando termina con el código de salida 6, que en un script te permite distinguir este caso. | Si usas el CLI, no necesitas leer las cabeceras del límite, porque el comando lo respeta por ti. Si lo usas desde un script, revisa el código de salida, que se explica en la [referencia del CLI](/v1/guias/cli-referencia#codigos-de-salida). ## Siguientes pasos - [Buenas prácticas](/v1/guias/buenas-practicas): estrategia de reintentos con código listo para copiar. - [Límites](/v1/guias/limites): tamaño del cuerpo, paginación y otros topes por petición. - [Consumo y cuotas](/v1/guias/consumo): consulta tu cupo de documentos antes de un lote grande. - [Errores](/v1/guias/errores): todos los códigos y si se reintentan. --- # Ambientes y contribuyentes Pruebas y producción comparten el mismo contrato y solo cambian la URL y la API Key; aquí ves cómo pasar a producción y qué identificación usar. Puedes trabajar con nuestra API en dos ambientes: uno de pruebas, para desarrollar sin validez fiscal, y otro de producción, para emitir comprobantes reales. Aquí ves en qué se diferencian, qué te recomendamos comprobar antes de pasar a producción y cómo se identifica cada contribuyente en las rutas y en el cuerpo de las peticiones. Consúltala cuando prepares tu integración para producción o cuando una petición te devuelva un 403 o un 422 por la identificación del contribuyente. Al terminar sabrás qué URL y qué API Key usar en cada ambiente, y qué valor del contexto va en cada lugar. ## Conceptos - **Ambiente.** El SRI tiene dos ambientes: **pruebas**, donde los comprobantes no tienen validez fiscal, y **producción**, donde sí la tienen. Para cada uno te damos una URL de la API distinta. - **Contribuyente.** Es la persona o empresa en cuyo nombre emites, y se identifica con su RUC de 13 dígitos o con la identificación con la que está registrado, de 5 a 13 dígitos. Una integración puede emitir para varios contribuyentes con la misma API Key. - **Clave de acceso.** Es el número de 49 dígitos que identifica cada comprobante ante el SRI. Nosotros la asignamos por ti. Todos los términos están en el [Glosario](/v1/guias/glosario). ## Ambientes | | Pruebas | Producción | |---|---|---| | URL base del API | `https://api-sandbox.mynexusapi.com` | `https://api.mynexusapi.com` | | Validez fiscal | No | Sí | | Código de ambiente (`ambiente` en el seguimiento y dígito 24 de la clave de acceso) | `1` | `2` | | Alta por autoservicio | Sí, con el [Sandbox de pruebas](/v1/guias/sandbox). | Sí, desde **Pasar a producción** al cumplir las condiciones. | | Portal del Cliente | `https://portal.mynexusapi.com` (alta en `/sandbox`; el sandbox se administra desde este portal). | `https://portal.mynexusapi.com` (el mismo portal; el paso a producción se hace desde **Pasar a producción**). | | API Key | Propia del ambiente de pruebas. | Propia del ambiente de producción. | | IP de origen | Se acepta cualquier IP. | Solo las IP registradas en **Cuenta > IP permitidas**. Si no registraste ninguna, una API Key limitada a servicios y RUC concretos funciona desde cualquier IP. | | Cupo | Paquete de pruebas de 3.000 documentos, sin vencimiento ni renovación automática. | Paquetes comprados, de un año desde el pago. | | Reglas del comprobante, secuencial, idempotencia y errores | Iguales. | Iguales. | El contrato, los campos y los códigos de error son los mismos en los dos ambientes, así que el código que funciona en pruebas funciona en producción con solo cambiar la URL base y la API Key, y registrar tu IP de salida. > [!WARNING] > Todo lo que emitas con la URL de producción se envía al SRI con validez > fiscal y no se puede deshacer desde la API. Usa la URL de producción solo > después de completar la lista de verificación de abajo, y guárdala en tu > configuración, no en el código. ## Cómo pasar a producción Antes de emitir el primer comprobante real, revisa que cumples cada punto de esta lista. Los primeros cinco se comprueban en pruebas; los demás, ya con la habilitación de producción. - [ ] Ejecutaste en pruebas los [casos de prueba](/v1/guias/datos-de-prueba#casos-de-prueba) y tu sistema reacciona bien a cada uno. - [ ] Tu sistema guarda `idOperacion`, `Idempotency-Key` y `claveAcceso` junto a cada documento. - [ ] Reintentas con la misma `Idempotency-Key` ante timeouts y errores de red. - [ ] Recibes el resultado por [webhook](/v1/guias/webhooks) y verificas la [firma](/v1/guias/webhooks-firma), o haces un seguimiento con espera y un número máximo de consultas. - [ ] Solo marcas un comprobante como válido cuando el `estado` de la operación es `autorizado`. - [ ] Completaste **Pasar a producción** en el Portal del Cliente, con el RUC de cada contribuyente y las IP de salida de tus servidores de producción. La API Key de producción se muestra una sola vez al confirmar. - [ ] Recibiste la API Key de producción y la guardaste como secreto, separada de la de pruebas. - [ ] Las IP de salida de producción están registradas en el Portal del Cliente, en **Cuenta > IP permitidas**. - [ ] `GET https://api.mynexusapi.com/v1/contexto` con la API Key de producción responde 200 y lista tus contribuyentes con `puedeEmitir: true`. - [ ] Cambiaste en tu configuración la URL base a `https://api.mynexusapi.com` y la API Key a la de producción. - [ ] Decidiste la numeración de cada `estab` y `ptoEmi` de producción: el secuencial automático o el de tu sistema. Los secuenciales de pruebas y de producción son series independientes, así que los números que usaste en pruebas no ocupan números en producción. ## Contribuyentes de tu integración `GET /v1/contexto` lista los contribuyentes para los que tu API Key puede operar en el ambiente de la URL que llamas. Te recomendamos consultarlo al iniciar tu sistema para saber qué identificación usar y qué tipos de comprobante tienes habilitados; todos sus campos están en [Contexto](/v1/guias/consulta-contexto). | Campo | Qué es | Dónde se usa | |---|---|---| | `identificacion` | La identificación completa del contribuyente, tal como está registrada: su RUC de 13 dígitos o una identificación de 5 a 13 dígitos. | En la ruta `/v1/contribuyentes/{identificacion}/...` y en el cuerpo, en `infoTributaria.ruc`. | | `puedeEmitir` | Vale `true` si puedes emitir para este contribuyente. | Antes de emitir. | | `puedeRecibir` | Indica si el contribuyente tiene habilitada la recepción. | Es informativo y no afecta la emisión. | | `tiposComprobante` | Los códigos habilitados (`01`, `03`, `04`, `05`, `06`, `07`). | Antes de emitir cada tipo. | Si un contribuyente no aparece en el contexto, no está habilitado para tu API Key en ese ambiente. Si lo necesitas, puedes solicitar su alta por el canal comercial. ## Identificación en la ruta y RUC en el cuerpo La ruta y el cuerpo usan el mismo valor: la `identificacion` del contexto, que es la identificación completa del contribuyente. Con el contribuyente de prueba, la `identificacion` es `0123456789001`, y la usas así: ``` POST /v1/contribuyentes/0123456789001/facturas ``` El siguiente fragmento muestra solo los campos de identificación del cuerpo; el cuerpo completo de cada comprobante está en la guía de su tipo. ```json { "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001" } } ``` La misma `identificacion` va en las demás rutas del contribuyente: las descargas del RIDE y del XML y el perfil del emisor. Si los valores no coinciden, la API responde así: | Si envías | Respuesta | Qué hacer | |---|---|---| | En la ruta, una identificación que no es de ninguno de tus contribuyentes | 403 con el `codEstado` 3011 (`acceso_denegado`). | Usa una `identificacion` del contexto. | | En `infoTributaria.ruc`, un valor distinto de la `identificacion` de la ruta | 422 con el `codEstado` 3002 (`comprobante_invalido`). | Envía en `infoTributaria.ruc` la misma `identificacion` de la ruta. | `infoTributaria.ruc` admite solo dígitos, de 5 a 13. ## Clave de acceso La clave de acceso es el identificador del comprobante ante el SRI. Tiene 49 dígitos y nosotros la asignamos, por eso la solicitud de emisión no tiene un campo `claveAcceso`; si lo envías, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`). La recibes en el seguimiento (`GET /v1/operaciones/{idOperacion}`) y en los webhooks, y la usas para descargar el RIDE y el XML. La tabla desglosa la clave de ejemplo `0710202601012345678900110010010000001231234567811`: | Posición | Dígitos | Contenido | En el ejemplo | |---|---|---|---| | 1-8 | 8 | Fecha de emisión (`ddMMyyyy`) | `07102026` | | 9-10 | 2 | Tipo de comprobante (`tipoDocumento`) | `01` | | 11-23 | 13 | RUC del emisor | `0123456789001` | | 24 | 1 | Ambiente (`1` pruebas, `2` producción) | `1` | | 25-30 | 6 | Serie: establecimiento + punto de emisión | `001001` | | 31-39 | 9 | Secuencial | `000000123` | | 40-47 | 8 | Código numérico | `12345678` | | 48 | 1 | Tipo de emisión (`1` normal) | `1` | | 49 | 1 | Dígito verificador (módulo 11) | `1` | La clave es única por ambiente: el mismo comprobante tiene claves distintas en pruebas y en producción. Si quieres revisar una clave sin emitir nada, usa [Decodificar clave de acceso](/v1/guias/consulta-clave-acceso). ## Errores de este apartado | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 3009 (`credenciales_invalidas`) | 401 | La API Key no es del ambiente de la URL (por ejemplo, la de pruebas contra la URL de producción). | Corrige la configuración: usa la API Key del ambiente de la URL. | | 3011 (`acceso_denegado`) | 403 | El contribuyente de la ruta no está habilitado para tu API Key en este ambiente, o el tipo de comprobante no está habilitado. | Corrige la ruta con una `identificacion` del contexto de ese ambiente o solicita la habilitación. | | 3002 (`comprobante_invalido`) | 422 | Enviaste `ambiente`, `tipoEmision` o `claveAcceso`, o `infoTributaria.ruc` es distinto de la `identificacion` de la ruta. | Corrige el cuerpo: quita esos campos y envía en `infoTributaria.ruc` la `identificacion` de la ruta. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada o la API no pudo identificar la IP de origen. El sandbox no exige IP registrada. | Registra tu IP de producción en el portal o llama sin proxies que oculten el origen. Si persiste, abre un ticket con el valor de `X-Correlation-Id`. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Contexto](/v1/guias/consulta-contexto): todos los campos de `GET /v1/contexto`. - [Datos de prueba](/v1/guias/datos-de-prueba): los casos que debes probar antes de producción. - [Comprobantes electrónicos](/v1/guias/emision): la estructura de cada tipo de comprobante. - [Buenas prácticas](/v1/guias/buenas-practicas): reintentos, idempotencia y manejo de secretos en producción. --- # Buenas prácticas Las prácticas que hacen estable una integración en producción, desde la idempotencia y los reintentos hasta el cupo y la seguridad. Una integración que funciona en pruebas puede fallar en producción por motivos que no tienen que ver con el comprobante: un timeout, un corte de red, un proceso que se reinicia a mitad de un envío o un lote que supera el límite de solicitudes. Aquí te recomendamos las prácticas que evitan esos problemas, con código listo para copiar en cada caso. Te sugerimos leerla antes de pasar a producción y volver a ella cuando diseñes los reintentos, la emisión en lote o el seguimiento. Al final tienes una lista de verificación con todo lo que te conviene tener resuelto. ## Conceptos - **Idempotencia.** Repetir la misma petición produce el mismo efecto que hacerla una vez. En la emisión la consigues con la cabecera `Idempotency-Key`: si tu proceso reenvía un comprobante porque no supo si llegó, la API reconoce la intención y no crea un segundo comprobante. Más detalle en [Idempotencia](/v1/guias/glosario#idempotencia). - **Reintento con espera exponencial y jitter.** Ante un fallo temporal esperas cada vez más entre intentos (1, 2, 4, 8 segundos...) y agregas un componente aleatorio, el *jitter*, para que muchos clientes no reintenten al mismo tiempo. - **Asincronía.** La emisión responde `202 Accepted` cuando **recibe** el comprobante, y la autorización del SRI llega después. El recorrido completo está en [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida). ## Idempotencia ### Reglas de la Idempotency-Key La cabecera `Idempotency-Key` identifica la intención de emitir un comprobante concreto. Estas son sus reglas: | Regla | Valor | |---|---| | Obligatoria | Sí, en la ruta de emisión del tipo, por ejemplo `POST /v1/contribuyentes/{identificacion}/facturas` para una factura. Si falta, la API responde 400 con el `codEstado` 3003 (`solicitud_invalida`). | | Longitud | De 1 a 128 caracteres. | | Caracteres | Letras ASCII sin tildes (`A-Z`, `a-z`), dígitos (`0-9`) y `-` `_` `.` `:` `/`. | | Alcance | Tu integración (todas tus API Key) y el ambiente. La misma clave en pruebas y en producción son intenciones distintas. | | Retención | 7 días desde que se usó por primera vez. | ### Qué responde la API La respuesta depende de si la clave y el cuerpo ya se habían usado: | Envías | Respuesta | Qué significa | |---|---|---| | Clave nueva | 202 con `estado` en `recibido` y un `idOperacion` nuevo. | La API recibió una emisión nueva. | | Misma clave y mismo cuerpo admitido | Un 202 con el mismo `idOperacion` y el estado actual de la operación. | La API reconoce el reintento y no crea otro comprobante. | | Misma clave y mismo cuerpo rechazado con 422 | El mismo 422 de validación, sin otro consumo. | Corrige el documento antes de usar una nueva clave. | | Misma clave y otro cuerpo | 409 con el `codEstado` 3005 (`conflicto_idempotencia`). | Hay un conflicto, porque esa clave ya pertenece a otra intención. | | Otra clave, misma `referenciaExterna` (con el mismo `origenReferencia`) y mismo cuerpo | Un 202 con el mismo `idOperacion` y el estado actual de la operación. | La referencia también identifica la intención. | | Otra clave, misma `referenciaExterna` y otro cuerpo | 409 si la operación sigue pendiente o fue autorizada. Tras un rechazo terminal admite la corrección con 202. | La corrección de un comprobante rechazado consume un documento. | "Mismo cuerpo" significa el mismo contenido del comprobante. Si en el reintento cambias un importe, una fecha o el orden de los detalles, la API lo trata como otro cuerpo. ### Cómo generar y guardar la clave Elige una de estas dos formas y aplícala siempre igual: | Forma | Ejemplo | Cuándo conviene | |---|---|---| | Derivada de tu documento interno | `FACTURA-2026-0001` (tu número interno de factura) | Cuando tu sistema ya tiene un identificador único y estable por documento. | | UUID v4 generado una vez | `5b0c6f6e-3c2a-4d7e-9a51-7f2f0d6b2c11` | Cuando no tienes un identificador estable o puede repetirse entre sistemas. | Lo importante es **guardar** la clave antes del primer envío, para poder reutilizarla en cualquier reintento: 1. Al crear el documento en tu sistema, genera la `Idempotency-Key` y la `referenciaExterna` y guárdalas en la misma fila, dentro de la misma transacción de base de datos. 2. Envía la emisión con esos valores. 3. Si no recibes respuesta porque hubo un timeout, un corte de red o tu proceso se reinició, lee los valores guardados y reenvía **el mismo cuerpo** con **la misma clave**. 4. Al recibir el 202, guarda el `idOperacion` en la misma fila. > [!WARNING] > No generes una `Idempotency-Key` nueva en cada intento. Si el primer envío > llegó y reintentas con otra clave y otra `referenciaExterna`, puedes emitir dos > comprobantes con validez fiscal. ### Ejemplo Guarda el JSON de [Factura](/v1/guias/emision-01) como `comprobante.json`. El tipo de comprobante lo fija la ruta de emisión, así que este ejemplo emite una factura en `/v1/contribuyentes/{identificacion}/facturas`. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```bash curl -s -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: FACTURA-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas"); peticion.Headers.Add("Idempotency-Key", "FACTURA-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "FACTURA-2026-0001", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'FACTURA-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: FACTURA-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "FACTURA-2026-0001") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; // client: cliente EcuafactClient - ver SDK .NET. comprobante: tu Estructura del comprobante. // Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado. EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001"); string clave = resultado.IdempotencyKey; // guardala para reintentos de tu aplicacion ``` ```python-sdk # client: cliente EcuafactClient - ver SDK Python. comprobante: tu Estructura del comprobante. # Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado. resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001") clave = resultado.idempotency_key # guardala para reintentos de tu aplicacion ``` ```javascript-sdk // client: cliente EcuafactClient - ver SDK Node.js. comprobante: tu Estructura del comprobante. // Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado. const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001"); const clave = resultado.idempotencyKey; // guardala para reintentos de tu aplicacion ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001'); $clave = $resultado->idempotencyKey; // guardala para reintentos de tu aplicacion ``` ```java-sdk import com.ecuafact.sdk.EmisionResultado; // client: cliente EcuafactClient - ver SDK Java. comprobante: tu Estructura del comprobante. // Pasa tu propia clave; si no la pasas, el SDK genera una y la devuelve en el resultado. EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001"); String clave = resultado.idempotencyKey(); // guardala para reintentos de tu aplicacion ``` ```bash-cli # Resultado esperado: el idOperacion de la emisión. Si repites el comando con el # mismo archivo, la API reconoce el reintento y no emite un segundo comprobante. ecuafact emitir comprobante.json --entorno sandbox ``` **Resultado esperado.** La primera vez recibes un 202 con `estado` en `recibido` y un `idOperacion`. Si ejecutas el mismo ejemplo otra vez sin cambiar `comprobante.json`, recibes un 202 con el mismo `idOperacion` y el estado actual de la operación, y así compruebas que tu reintento no duplica el comprobante. ## Errores y reintentos No todos los errores se reintentan. Los fallos temporales se repiten con el mismo cuerpo y la misma clave; los demás se corrigen antes de volver a enviar. | Situación | Reintentar | Cómo | |---|---|---| | Timeout o corte de red (no recibiste respuesta) | Sí | Reenvía el mismo cuerpo con la misma `Idempotency-Key`, con espera exponencial. | | 500 con el `codEstado` 5001 (`error_interno`), 502 con 5003 (`error_dependencia`), 503 con 5002 (`servicio_no_disponible`) o 504 con 5004 (`tiempo_agotado`) | Sí | Reenvía el mismo cuerpo con la misma `Idempotency-Key`, con espera exponencial. En un 503, respeta `Retry-After`. | | 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí | Espera al menos lo que indica `Retry-After` y repite la misma petición. | | 429 con el `codEstado` 4004 (`cupo_agotado`) | No | El cupo se agotó; amplíalo como se explica en [Consumo y cuotas](/v1/guias/consumo). | | 400, 401, 403, 404, 413, 415 o 422 | No | Corrige la causa, porque repetir la petición igual da el mismo error. | | 409 con el `codEstado` 3004 (`comprobante_duplicado`) | No | El número ya existe; busca el comprobante existente. | | 409 con el `codEstado` 3005 (`conflicto_idempotencia`) | No | Reenvía el cuerpo original, o usa una clave nueva si es otra emisión. | Decide siempre con el estado HTTP y el `codEstado` del cuerpo, nunca con el texto de `msgError`. El detalle de cada código está en el [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado). ## Reintentos con espera exponencial Para los errores que sí se reintentan, este es el algoritmo recomendado: | Parámetro | Valor sugerido | |---|---| | Intentos máximos | 5: el primero más 4 reintentos. | | Espera antes del reintento `n` | Aleatoria entre 0 y `min(60, 2^n)` segundos (jitter completo). | | Si la respuesta trae `Retry-After` | Espera el mayor valor entre `Retry-After` y la espera calculada. | | Timeout por intento | 30 segundos. | | Al agotar los intentos | Deja la emisión pendiente en tu sistema con su `Idempotency-Key` y reinténtala más tarde, por ejemplo en un proceso programado. | Si usas nuestros SDK oficiales, no necesitas programar estos reintentos: ya reintentan, con la misma `Idempotency-Key`, los errores de red y las respuestas 408, 425, 500, 502, 503 y 504. Por defecto hacen 3 intentos en total y respetan `Retry-After`. Un 429 con el `codEstado` 5005 también lo reintentan por defecto, después de esperar `Retry-After`, y un 429 con el `codEstado` 4004 no lo reintentan nunca; el detalle está en la guía de cada [SDK](/v1/guias/sdk). Los ejemplos siguientes son para integraciones HTTP directas. Para ejecutarlos, guarda el JSON de [Factura](/v1/guias/emision-01) como `comprobante.json`. ```csharp using System.Linq; using System.Net.Http; using System.Text; using System.Text.Json; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com"), Timeout = TimeSpan.FromSeconds(30) }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); string cuerpo = await File.ReadAllTextAsync("comprobante.json"); const string idempotencyKey = "FACTURA-2026-0001"; // guardada con tu documento ANTES del primer intento int[] reintentables = { 429, 500, 502, 503, 504 }; const int maxIntentos = 5; for (int intento = 1; intento <= maxIntentos; intento++) { TimeSpan retryAfter = TimeSpan.Zero; try { using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas"); peticion.Headers.Add("Idempotency-Key", idempotencyKey); peticion.Content = new StringContent(cuerpo, Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); int estado = (int)respuesta.StatusCode; string texto = await respuesta.Content.ReadAsStringAsync(); int codEstado = 0; try { codEstado = JsonDocument.Parse(texto).RootElement.GetProperty("codEstado").GetInt32(); } catch (Exception) { } // 4004 es cupo agotado: no se reintenta. 5005 es el limite de solicitudes: si. if (!reintentables.Contains(estado) || codEstado == 4004) { Console.WriteLine($"Respuesta definitiva: {estado} {texto}"); return; } retryAfter = respuesta.Headers.RetryAfter?.Delta ?? TimeSpan.Zero; Console.WriteLine($"Intento {intento}: HTTP {estado}"); } catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException) { Console.WriteLine($"Intento {intento}: sin respuesta ({ex.GetType().Name})"); } if (intento == maxIntentos) { break; } double tope = Math.Min(60, Math.Pow(2, intento)); TimeSpan calculada = TimeSpan.FromSeconds(Random.Shared.NextDouble() * tope); await Task.Delay(retryAfter > calculada ? retryAfter : calculada); } Console.WriteLine("Sin respuesta definitiva: reintenta mas tarde con la misma Idempotency-Key."); ``` ```python import json import os import random import time import requests URL = "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" IDEMPOTENCY_KEY = "FACTURA-2026-0001" # guardada con tu documento ANTES del primer intento REINTENTABLES = {429, 500, 502, 503, 504} MAX_INTENTOS = 5 with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) definitiva = False for intento in range(1, MAX_INTENTOS + 1): retry_after = 0.0 try: r = requests.post( URL, headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": IDEMPOTENCY_KEY, }, json=cuerpo, timeout=30, ) try: cod_estado = r.json().get("codEstado", 0) except ValueError: cod_estado = 0 # 4004 es cupo agotado: no se reintenta. 5005 es el limite de solicitudes: si. if r.status_code not in REINTENTABLES or cod_estado == 4004: print("Respuesta definitiva:", r.status_code, r.text) definitiva = True break retry_after = float(r.headers.get("Retry-After", "0")) print(f"Intento {intento}: HTTP {r.status_code}") except (requests.ConnectionError, requests.Timeout) as error: print(f"Intento {intento}: sin respuesta ({type(error).__name__})") if intento < MAX_INTENTOS: tope = min(60, 2 ** intento) time.sleep(max(retry_after, random.uniform(0, tope))) if not definitiva: print("Sin respuesta definitiva: reintenta mas tarde con la misma Idempotency-Key.") ``` ```javascript // Node.js 18 o superior. Guarda como reintentos.mjs y ejecuta: node reintentos.mjs import { readFile } from 'node:fs/promises'; const URL = 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas'; const IDEMPOTENCY_KEY = 'FACTURA-2026-0001'; // guardada con tu documento ANTES del primer intento const REINTENTABLES = new Set([429, 500, 502, 503, 504]); const MAX_INTENTOS = 5; const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms)); const cuerpo = await readFile('comprobante.json', 'utf8'); let definitiva = false; for (let intento = 1; intento <= MAX_INTENTOS && !definitiva; intento++) { let retryAfter = 0; try { const res = await fetch(URL, { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': IDEMPOTENCY_KEY, 'Content-Type': 'application/json' }, body: cuerpo, signal: AbortSignal.timeout(30000) }); const texto = await res.text(); let codEstado = 0; try { codEstado = JSON.parse(texto).codEstado ?? 0; } catch { } // 4004 es cupo agotado: no se reintenta. 5005 es el limite de solicitudes: si. if (!REINTENTABLES.has(res.status) || codEstado === 4004) { console.log('Respuesta definitiva:', res.status, texto); definitiva = true; break; } retryAfter = Number(res.headers.get('Retry-After') ?? 0); console.log(`Intento ${intento}: HTTP ${res.status}`); } catch (error) { console.log(`Intento ${intento}: sin respuesta (${error.name})`); } if (intento < MAX_INTENTOS) { const tope = Math.min(60, 2 ** intento); await esperar(Math.max(retryAfter, Math.random() * tope) * 1000); } } if (!definitiva) { console.log('Sin respuesta definitiva: reintenta mas tarde con la misma Idempotency-Key.'); } ``` ```php true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: ' . $idempotencyKey, 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => $cuerpo, CURLOPT_HEADERFUNCTION => function ($ch, $linea) use (&$retryAfter) { if (stripos($linea, 'Retry-After:') === 0) { $retryAfter = (int) trim(substr($linea, 12)); } return strlen($linea); }, ]); $respuesta = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($respuesta === false || $estado === 0) { echo "Intento $intento: sin respuesta" . PHP_EOL; } else { $json = json_decode($respuesta, true); $codEstado = is_array($json) ? (int) ($json['codEstado'] ?? 0) : 0; // 4004 es cupo agotado: no se reintenta. 5005 es el limite de solicitudes: si. if (!in_array($estado, $reintentables, true) || $codEstado === 4004) { echo "Respuesta definitiva: $estado $respuesta" . PHP_EOL; $definitiva = true; break; } echo "Intento $intento: HTTP $estado" . PHP_EOL; } if ($intento < $maxIntentos) { $tope = min(60, 2 ** $intento); $calculada = mt_rand() / mt_getrandmax() * $tope; usleep((int) (max($retryAfter, $calculada) * 1000000)); } } if (!$definitiva) { echo 'Sin respuesta definitiva: reintenta mas tarde con la misma Idempotency-Key.' . PHP_EOL; } ``` > [!WARNING] > Reintenta siempre con la **misma** `Idempotency-Key` y el **mismo** cuerpo. Un > reintento con una clave nueva después de un timeout puede crear un segundo > comprobante. ## Emisión en lote y concurrencia Cuando emites muchos comprobantes, a la vez o en poco tiempo, ten en cuenta estas pautas: - **Un número por comprobante.** No reutilices el mismo `estab` + `ptoEmi` + `secuencial` para otro comprobante. Si ese número ya está autorizado o pendiente, la API responde 409 con el `codEstado` 3004. - **Deja la numeración en nuestras manos.** Si omites `infoTributaria.secuencial` o lo envías en ceros, asignamos el siguiente número de la serie y evitas choques entre procesos paralelos. Más detalle en [Secuencial](/v1/guias/glosario#secuencial). - **Concurrencia moderada.** Puedes emitir en paralelo con la misma API Key. Empieza con 5 a 10 peticiones simultáneas y respeta el límite de tu integración, que es de 200 por minuto por defecto y de 60 en un sandbox, como se explica en [Límite de request](/v1/guias/limite-de-request). - **No reescribas en los reintentos.** Conserva las fechas, los importes y el orden de los detalles tal como los enviaste la primera vez. Si cambian, la API lo trata como otro cuerpo y responde 409 con el `codEstado` 3005. - **Solo campos del contrato.** No agregues campos propios a la Estructura del comprobante, porque un campo desconocido se rechaza con un 422 y el `codEstado` 3002 (`comprobante_invalido`), con el campo indicado en `errores`. Para datos extra, usa `infoAdicional`. - **Corrige después de confirmar un rechazo terminal.** Conserva el número y la referencia del comprobante rechazado; envía el contenido corregido con una `Idempotency-Key` nueva. La corrección consume un documento. Si reenvías el mismo contenido, conserva la clave original: recibirás la operación y su estado actual sin una nueva emisión. No reenvíes operaciones pendientes ni autorizadas. Ante un resultado no confirmado, consulta la operación y contacta a soporte antes de intentar otra emisión. ## Seguimiento del estado La emisión responde 202 cuando el comprobante queda **recibido**, no autorizado, así que no esperes el resultado fiscal en esa misma respuesta. Te recomendamos usar los [webhooks](/v1/guias/webhooks) como fuente principal y `GET /v1/operaciones/{idOperacion}` como respaldo. Si consultas, espacia las consultas, por ejemplo a los 10 segundos, a los 30, al minuto, a los 2 minutos y luego cada 5 minutos. Sigue consultando mientras el `estado` sea `recibido` y detente con cualquier otro valor, porque todos los demás son finales. Para fines fiscales solo cuenta un `estado` en `autorizado`; el detalle está en [Seguimiento de una operación](/v1/guias/consulta-operacion). ## Webhooks Si recibes el resultado por webhook, te recomendamos estas pautas en tu endpoint: - Verifica la firma `Ecuafact-Signature` sobre el **cuerpo crudo** antes de interpretar el evento, como se explica en [Verificación de firma](/v1/guias/webhooks-firma). - Guarda el evento, responde rápido con un 2xx y procésalo en segundo plano. Un timeout, un 408, un 429 o un 5xx provocan un reintento; un 3xx u otro 4xx dejan la entrega rechazada, sin reintentos. Ante un fallo temporal tuyo, responde 503 con `Retry-After`. - Trata los eventos como idempotentes, porque el mismo evento puede llegar más de una vez. Deduplica antes de actuar. - Ten un respaldo: si no recibes el webhook en un tiempo razonable, consulta la operación. ## Cupo El [cupo](/v1/guias/glosario#cupo) se mueve de forma distinta en cada etapa de una emisión: | Momento | Efecto en el cupo | |---|---| | Validación con `/validar` | No consume documentos. | | Emisión nueva admitida | Aparta una unidad al recibirla; se consume cuando la operación llega a un resultado final (autorizada o rechazada) y se libera si queda `cancelado`. | | Nuevo intento rechazado por formato o validación (422) | Consume una unidad; reutilizar la misma clave y cuerpo no vuelve a consumir. | | Reintento del mismo contenido | No consume otra unidad. | | Corrección de contenido tras un rechazo terminal | Consume una unidad. | | RUC no autorizado o emisor sin firma configurada | No consume documentos. | Antes de un lote grande, consulta [`GET /v1/consumo`](/v1/guias/consumo) y verifica que `disponibles` alcance. Sin cupo, la emisión responde 429 con el `codEstado` 4004; en ese caso no reintentes en bucle y amplía tu cupo primero. Además, valida bien tus comprobantes en pruebas, porque en producción cada rechazo del SRI gasta un documento. ## Formatos Los valores del comprobante siguen estos formatos: - Los importes son números JSON con punto decimal y sin comillas: `112.50`, no `"112,50"`. - Las fechas del comprobante son texto con el formato `dd/MM/yyyy`, y el periodo fiscal, `MM/yyyy`. - Los códigos y las identificaciones son texto y conservan los ceros a la izquierda (`"01"`, `"0123456789"`). - La codificación es UTF-8. ## Identifica tus solicitudes Puedes enviar dos cabeceras opcionales para ubicar una solicitud en tus logs y para que podamos encontrarla cuando nos pides soporte. Las reglas completas están en [Límites](/v1/guias/limites#cabeceras). | Cabecera | Para qué | Qué haces | |---|---|---| | `X-Correlation-Id` | Identifica la solicitud. La API lo devuelve en toda respuesta y, si envías uno válido (de 1 a 64 caracteres `A-Z a-z 0-9 . _ -`), lo reutiliza. | Envía el identificador de tu proceso, por ejemplo el número de pedido, y guarda el que vuelve en la respuesta junto a tu documento. | | `X-Additional-Info` | Es un texto tuyo con el que podemos encontrar tu llamada cuando nos pides soporte, aunque no tengas el `X-Correlation-Id`. No se guarda con el comprobante ni se devuelve en la respuesta. | Envía el nombre y la versión de tu sistema y datos operativos, por ejemplo `MiERP/4.2 sucursal=norte lote=42`. | `X-Additional-Info` tiene tres reglas: - [ ] Envía una sola cabecera por solicitud. - [ ] Usa solo ASCII imprimible, sin tildes, `ñ` ni saltos de línea, y como máximo 256 caracteres. Si no cumple, no podremos usarla para ubicar tu solicitud, pero la API tampoco la rechaza. - [ ] No incluyas datos personales (correos, cédulas, nombres) ni secretos (API Key, contraseñas). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```bash curl -s -i "https://api-sandbox.mynexusapi.com/v1/contexto" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "X-Correlation-Id: pedido-2026-0457" \ -H "X-Additional-Info: MiERP/4.2 sucursal=norte lote=42" # -i muestra las cabeceras: la respuesta trae X-Correlation-Id: pedido-2026-0457 ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); // En todas las solicitudes de este HttpClient. http.DefaultRequestHeaders.Add("X-Additional-Info", "MiERP/4.2 sucursal=norte lote=42"); using var peticion = new HttpRequestMessage(HttpMethod.Get, "/v1/contexto"); peticion.Headers.Add("X-Correlation-Id", "pedido-2026-0457"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); string correlacion = respuesta.Headers.TryGetValues("X-Correlation-Id", out IEnumerable? valores) ? valores.First() : ""; Console.WriteLine($"{(int)respuesta.StatusCode} X-Correlation-Id: {correlacion}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/contexto", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "X-Correlation-Id": "pedido-2026-0457", "X-Additional-Info": "MiERP/4.2 sucursal=norte lote=42", }, timeout=30, ) print(r.status_code, "X-Correlation-Id:", r.headers.get("X-Correlation-Id", "")) ``` ```javascript // Node.js 18 o superior. Guarda como identificar.mjs y ejecuta: node identificar.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'X-Correlation-Id': 'pedido-2026-0457', 'X-Additional-Info': 'MiERP/4.2 sucursal=norte lote=42' } }); console.log(res.status, 'X-Correlation-Id:', res.headers.get('X-Correlation-Id') ?? ''); ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'X-Correlation-Id: pedido-2026-0457', 'X-Additional-Info: MiERP/4.2 sucursal=norte lote=42', ], CURLOPT_HEADERFUNCTION => function ($ch, string $linea) use (&$correlacion): int { if (stripos($linea, 'X-Correlation-Id:') === 0) { $correlacion = trim(substr($linea, strlen('X-Correlation-Id:'))); } return strlen($linea); }, ]); curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' X-Correlation-Id: ' . $correlacion . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contexto")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("X-Correlation-Id", "pedido-2026-0457") .header("X-Additional-Info", "MiERP/4.2 sucursal=norte lote=42") .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " X-Correlation-Id: " + respuesta.headers().firstValue("X-Correlation-Id").orElse("")); ``` Con los SDK, configura `X-Additional-Info` una vez en el cliente y cambia la correlación o el texto en una sola llamada con las opciones por llamada. Ver [SDKs](/v1/guias/sdk#informacion-adicional). ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!, AdditionalInfo = "MiERP/4.2 sucursal=norte" }); Contexto contexto = await client.GetContextoAsync(opciones: new RequestOptions { CorrelationId = "pedido-2026-0457", AdditionalInfo = "MiERP/4.2 sucursal=norte lote=42" }); Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions, RequestOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], additional_info="MiERP/4.2 sucursal=norte", )) as client: contexto = client.get_contexto(opciones=RequestOptions( correlation_id="pedido-2026-0457", additional_info="MiERP/4.2 sucursal=norte lote=42", )) print(f"Contribuyentes: {len(contexto.contribuyentes or [])}") ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY, additionalInfo: "MiERP/4.2 sucursal=norte" }); const contexto = await client.getContexto({ correlationId: "pedido-2026-0457", additionalInfo: "MiERP/4.2 sucursal=norte lote=42" }); console.log(`Contribuyentes: ${contexto.contribuyentes.length}`); ``` ```php-sdk getContexto(new RequestOptions( correlationId: 'pedido-2026-0457', additionalInfo: 'MiERP/4.2 sucursal=norte lote=42', )); echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.RequestOptions; import com.ecuafact.sdk.contracts.Contexto; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")) .additionalInfo("MiERP/4.2 sucursal=norte")); Contexto contexto = client.getContexto(RequestOptions.create() .correlationId("pedido-2026-0457") .additionalInfo("MiERP/4.2 sucursal=norte lote=42")); System.out.println("Contribuyentes: " + contexto.contribuyentes().size()); ``` **Resultado esperado.** La API responde 200 y la respuesta trae la cabecera `X-Correlation-Id: pedido-2026-0457`. `X-Additional-Info` no cambia la respuesta; cuando pidas soporte, incluye el valor que enviaste, como se explica en [Cómo pedir soporte](/v1/guias/errores#como-pedir-soporte). ## Seguridad La API Key permite emitir comprobantes a nombre de tus contribuyentes, así que protégela como cualquier otro secreto de producción: - Envía `X-Api-Key` **solo** desde tu backend, nunca desde el navegador ni desde una app móvil. Cómo guardarla se explica en [Autenticación](/v1/guias/autenticacion#guarda-la-api-key). - Registra solo las IP de salida que de verdad llaman a la API. - Usa una API Key por sistema y rótala si alguien con acceso deja el equipo. - No escribas la API Key ni el secreto del webhook en los logs. ## Checklist antes de producción Antes de pasar a producción, comprueba que tu integración cumple cada punto: - [ ] Generas la `Idempotency-Key` y la `referenciaExterna` una vez por documento y las guardas antes del primer envío. - [ ] Reintentas con espera exponencial y jitter los timeouts, los 429 con el `codEstado` 5005 y los 500, 502, 503 y 504. - [ ] No reintentas automáticamente los 400, 401, 403, 409, 413, 422 ni los 429 con el `codEstado` 4004. - [ ] Cada emisión lleva un número de comprobante único, o usas el secuencial automático. - [ ] Tu webhook verifica la firma, responde rápido y deduplica los eventos. - [ ] Registras el `X-Correlation-Id` en tus logs junto a cada respuesta. - [ ] Envías `X-Additional-Info` con el nombre y la versión de tu sistema en cada solicitud, sin datos personales ni secretos, como se explica en [Identifica tus solicitudes](#identifica-tus-solicitudes). - [ ] Vigilas el saldo de tu cupo en `/v1/consumo`. - [ ] La API Key de producción está en un gestor de secretos y las IP de producción están registradas. ## Siguientes pasos - [Errores](/v1/guias/errores): qué significa cada código y si se reintenta. - [Webhooks](/v1/guias/webhooks): recibe el resultado de tus emisiones sin consultar. - [Límite de request](/v1/guias/limite-de-request): cuántas solicitudes por minuto puedes hacer. - [Consumo y cuotas](/v1/guias/consumo): consulta tu cupo antes de un lote. --- # Comprobantes electrónicos Emite los seis comprobantes del SRI con una ruta por tipo y una estructura JSON común, y sigue después su autorización. Puedes emitir todos los comprobantes electrónicos, desde la factura hasta el comprobante de retención, con el mismo flujo. Eliges la ruta según el tipo, envías el JSON del comprobante, la API lo valida y te responde 202 Accepted con un `idOperacion`; el resultado del SRI llega después, y puedes consultarlo o recibirlo por webhook. En esta página encuentras lo que comparten los seis tipos: las rutas y sus cabeceras, la estructura del cuerpo, las reglas de formato, cómo cuadrar los totales, la respuesta, cómo validar un comprobante sin emitirlo, los mensajes de validación y cómo reintentar sin emitir dos veces. Los campos propios de cada tipo están en su guía, que encuentras en [Cómo elegir el tipo de comprobante](#como-elegir-el-tipo-de-comprobante). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Todos los ejemplos de esta página usan > `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba). ## 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: ```text Construye en este proyecto la emisión de comprobantes con la API de Ecuafact y valida un comprobante de prueba antes de emitirlo. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, instálala 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/emision.md antes de escribir código; no inventes campos. Reutiliza el lenguaje y el SDK de Ecuafact que el proyecto ya use; si no usa ninguno, recomiéndame el SDK de su lenguaje (o el CLI ecuafact para probar, o el MCP para operar mi cuenta), con una frase de motivo y espera mi respuesta; HTTP directo solo si lo prefiero. Averigua de dónde salen los datos en este proyecto y mapea cada dato a la guía, sin inventar campos: el tipo se elige con la guía de su comprobante, los importes se calculan con las reglas de la guía y el secuencial puede omitirse. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno; nunca la pegues en el chat ni la imprimas. Valida con POST /v1/contribuyentes/{identificacion}/{tipo}/validar antes de emitir, donde {tipo} es la ruta del comprobante (facturas, liquidaciones-compra, notas-credito, notas-debito, guias-remision, retenciones), y no envíes infoTributaria.tipoDocumento en el cuerpo; solo si valida, emite con POST /v1/contribuyentes/{identificacion}/{tipo}, una Idempotency-Key estable y una referenciaExterna propia. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide siempre por estado y codEstado, usa urlEstado tal cual y lee errores como arreglo. Ejecuta una validación y una emisión de prueba e informa solo el resultado de la validación, el estado y el codEstado de la emisión, y cualquier acción que yo deba hacer. ``` ## Conceptos Si ya emitiste comprobantes electrónicos, puedes pasar directamente al [Endpoint](#endpoint). Si no, estos son los conceptos que usa el resto de la página. - Un [comprobante electrónico](/v1/guias/glosario) es el documento fiscal que el [SRI](/v1/guias/glosario), la autoridad tributaria del Ecuador, debe autorizar para que tenga validez. Puede ser una factura, una liquidación de compra, una nota de crédito, una nota de débito, una guía de remisión o un comprobante de retención. - La emisión es **asíncrona**. Tú envías el comprobante, la API lo valida y responde 202 Accepted, con lo que el comprobante queda **recibido**, todavía no autorizado. El resultado del SRI llega segundos o minutos después, y lo conoces por [seguimiento](/v1/guias/consulta-operacion) o por [webhook](/v1/guias/webhooks). - Cada comprobante tiene un **número** con la forma `estab-ptoEmi-secuencial`, por ejemplo `002-001-000000124`. Se compone del [establecimiento](/v1/guias/glosario) y el [punto de emisión](/v1/guias/glosario), de 3 dígitos cada uno, y del [secuencial](/v1/guias/glosario), un consecutivo de 9 dígitos dentro de esa serie. - La [clave de acceso](/v1/guias/glosario) es el número de 49 dígitos que identifica al comprobante ante el SRI. **No la envías**: te la asignamos nosotros y la ves en el seguimiento o en el webhook. - El [RIDE](/v1/guias/glosario), el PDF del comprobante, se descarga cuando el comprobante ya está autorizado. ## Endpoint La emisión tiene una ruta por tipo de comprobante. El tipo lo fija la ruta y no el cuerpo: no envíes `infoTributaria.tipoDocumento`, y `info` solo lleva los campos de ese tipo. Elige la ruta según el comprobante que emites. | Tipo | Código | Ruta de emisión | Ruta de validación | |---|---|---|---| | Factura | `01` | `POST /v1/contribuyentes/{identificacion}/facturas` | `POST /v1/contribuyentes/{identificacion}/facturas/validar` | | Liquidación de compra | `03` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra/validar` | | Nota de crédito | `04` | `POST /v1/contribuyentes/{identificacion}/notas-credito` | `POST /v1/contribuyentes/{identificacion}/notas-credito/validar` | | Nota de débito | `05` | `POST /v1/contribuyentes/{identificacion}/notas-debito` | `POST /v1/contribuyentes/{identificacion}/notas-debito/validar` | | Guía de remisión | `06` | `POST /v1/contribuyentes/{identificacion}/guias-remision` | `POST /v1/contribuyentes/{identificacion}/guias-remision/validar` | | Comprobante de retención | `07` | `POST /v1/contribuyentes/{identificacion}/retenciones` | `POST /v1/contribuyentes/{identificacion}/retenciones/validar` | Todas las rutas usan las mismas cabeceras. El siguiente es el ejemplo de una factura; cambia `facturas` por el segmento del tipo que emites. ``` POST /v1/contribuyentes/{identificacion}/facturas X-Api-Key: Idempotency-Key: Content-Type: application/json ``` | Nombre | Dónde | Tipo | Obligatorio | Descripción | |---|---|---|---|---| | `identificacion` | Ruta | string | Sí | El valor `contribuyentes[].identificacion` de [`GET /v1/contexto`](/v1/guias/consulta-contexto). Es la identificación completa del contribuyente, la misma que envías en `infoTributaria.ruc`; en pruebas, `0123456789001`. | | `X-Api-Key` | Cabecera | string | Sí | Tu [API Key](/v1/guias/autenticacion). | | `Idempotency-Key` | Cabecera | string | Sí | Identifica la intención de emitir este comprobante. Admite hasta 128 caracteres entre letras y dígitos ASCII y `-` `_` `.` `:` `/`. Su uso se explica en [Reintentos y duplicados](#reintentos-y-duplicados). | | `Content-Type` | Cabecera | string | Sí | `application/json`, o `application/xml` / `text/xml` si envías el XML del SRI. | | `X-Additional-Info` | Cabecera | string | No | Texto tuyo que identifica la solicitud cuando pides soporte. Sus reglas están en [Límites](/v1/guias/limites#cabeceras). | El cuerpo admite hasta 2 MiB y 32 niveles de anidamiento JSON. Si es mayor, la API responde 413 con el `codEstado` 3006 (`cuerpo_excedido`). ## Cuerpo JSON o XML Los seis endpoints de emisión y sus seis validaciones aceptan el mismo comprobante en JSON o en el XML del SRI. En los dos casos la ruta fija el tipo, y el `Content-Type` de tu petición indica el formato del cuerpo. | Regla | JSON | XML | |---|---|---| | `Content-Type` | `application/json` | `application/xml` o `text/xml` | | Tipo de comprobante | Lo fija la ruta | La raíz y `infoTributaria.codDoc` deben coincidir con la ruta | | Tamaño máximo | 2 MiB | 2 MiB | | Validación, cupo e idempotencia | Sí | Sí, con las mismas reglas | | Firma | La hace la plataforma | Se ignora la firma del XML; la plataforma vuelve a firmar | | `origenReferencia` | Lo envías tú | `xml-sri` | | `referenciaExterna` | La envías tú | La `claveAcceso` si no es cero; si no, `codDoc-estab-ptoEmi-secuencial` | El XML puede estar firmado o sin firmar, porque la API descarta ``. En `infoTributaria` puedes dejar los elementos propios del XML del SRI (`ambiente`, `tipoEmision`, `razonSocial`, `nombreComercial`, `claveAcceso`, `codDoc`, `dirMatriz`, `agenteRetencion`, `contribuyenteRimpe` y `regimenMicroempresas`), que se ignoran. Cualquier otro elemento que no pertenezca al contrato se rechaza con un 400 y el `codEstado` 3003 (`solicitud_invalida`). La retención debe usar el XML 2.0 con `docsSustento`; el XML 1.0 que trae `impuestos` en la raíz responde 422 con el `codEstado` 3002 (`comprobante_invalido`). ```bash curl -X POST "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: factura-xml-001" \ -H "Content-Type: application/xml" \ --data-binary @factura.xml ``` La respuesta es la misma que con JSON: un 202 con el `estado` `recibido` o el rechazo con su `codEstado`. En las rutas `/validar` el XML se envía igual y la `Idempotency-Key` se ignora. ## Antes de empezar - [ ] Una API Key de pruebas. Si todavía no tienes una, [crea tu sandbox](/v1/guias/sandbox). - [ ] En el ambiente de pruebas puedes llamar desde cualquier IP. En producción, la IP desde la que llamas debe estar registrada para tu API Key; si no lo está, la API responde 403 con el `codEstado` 3010 (`ip_no_autorizada`). - [ ] La `identificacion` del contribuyente, que obtienes de [`GET /v1/contexto`](/v1/guias/consulta-contexto). - [ ] El tipo de comprobante habilitado, es decir, que aparezca en `contribuyentes[].tiposComprobante` del contexto. - [ ] La variable de entorno `ECUAFACT_API_KEY` con tu API Key, para ejecutar los ejemplos. ## Cómo elegir el tipo de comprobante Elige el tipo según lo que necesitas documentar. Cada uno tiene su guía, con sus campos propios y un ejemplo completo listo para copiar. | Si quieres... | Emite | Código SRI | Guía | |---|---|---|---| | Cobrar una venta de bienes o servicios | Factura | `01` | [Factura](/v1/guias/emision-01) | | Documentar una compra a quien no puede emitirte factura (persona natural sin RUC, proveedor del exterior sin domicilio en Ecuador) | Liquidación de compra | `03` | [Liquidación de compra](/v1/guias/emision-03) | | Devolver dinero, aplicar un descuento posterior o anular total o parcialmente una factura ya autorizada | Nota de crédito | `04` | [Nota de crédito](/v1/guias/emision-04) | | Cobrar un valor adicional sobre una factura ya emitida (intereses por mora, recargos, gastos de cobranza) | Nota de débito | `05` | [Nota de débito](/v1/guias/emision-05) | | Acompañar el traslado de mercadería de un lugar a otro | Guía de remisión | `06` | [Guía de remisión](/v1/guias/emision-06) | | Dejar constancia de los impuestos que retienes al pagar a un proveedor | Comprobante de retención | `07` | [Comprobante de retención](/v1/guias/emision-07) | Un comprobante autorizado no se edita. Si una factura autorizada tiene un error, revierte su efecto con una nota de crédito y, si corresponde, emite una factura nueva y correcta. ## Estructura del comprobante Todos los tipos usan la misma estructura JSON. El tipo lo fija la ruta que llamas, así que el cuerpo no lleva `infoTributaria.tipoDocumento`. Lo que cambia de un tipo a otro son los campos que admite `info` y la colección de líneas. | Clave | Tipo | Obligatorio | Contenido | |---|---|---|---| | `origenReferencia` | string | Sí | Nombre estable del sistema que emite, por ejemplo `MiERP`. Se explica en [origenReferencia y referenciaExterna](#origenreferencia-y-referenciaexterna). | | `referenciaExterna` | string | Sí | Identificador del documento en tu sistema, por ejemplo `FACTURA-2026-0001`. | | `infoTributaria` | object | Sí | Identidad del comprobante: emisor y serie. Sus campos están en la tabla siguiente. | | `info` | object | Sí | Cabecera del comprobante. Solo admite los campos del tipo de la ruta; con un campo de otro tipo, la API responde 422. | | `detalles` | array | Según tipo | Líneas de factura (`01`), liquidación de compra (`03`) y nota de crédito (`04`). | | `motivos` | array | Según tipo | Motivos de la nota de débito (`05`). | | `destinatarios` | array | Según tipo | Destinatario y mercadería de la guía de remisión (`06`). | | `docsSustento` | array | Según tipo | Documento sustento y retenciones del comprobante de retención (`07`). | | `infoAdicional` | array | No | Hasta 15 objetos `{ "nombre", "valor" }` (cada uno de 1 a 300 caracteres) que se imprimen en el RIDE. | Si envías una colección que no corresponde al tipo, por ejemplo `motivos` en una factura, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`) y el mensaje `$.motivos: Campo no soportado en este contrato.` ### `infoTributaria` El tipo de comprobante no va en este objeto: lo fija la ruta. Envía solo el RUC del emisor y la serie del documento. | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `ruc` | string | Sí | RUC del emisor, de 5 a 13 dígitos. Envía la misma `identificacion` de la ruta, que es la identificación completa del contexto; en pruebas, `0123456789001`. Si es distinto de la identificación de la ruta, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `estab` | string | Sí | Establecimiento, de hasta 3 dígitos. Se completa con ceros a la izquierda, así que `2` se toma como `002`. | | `ptoEmi` | string | Sí | Punto de emisión, de hasta 3 dígitos. Se completa con ceros a la izquierda. | | `secuencial` | string | No | Secuencial, de hasta 9 dígitos, entre `1` y `999999999`. Omítelo y te asignamos el siguiente, como se explica en [Secuencial automático](#secuencial-automatico). | No envíes `tipoDocumento`, `claveAcceso`, `ambiente`, `tipoEmision`, `version` ni `formato`, ni en la raíz ni en `infoTributaria`. La API no admite esos campos y responde 422 con el `codEstado` 3002 (`comprobante_invalido`), con un detalle en `errores` como `"$.infoTributaria.tipoDocumento: Campo no soportado en este contrato."`. El tipo lo fija la ruta y el ambiente lo define la URL que llamas; la validación sin emitir aplica la misma regla. ### Qué cambia por tipo Cada tipo usa una contraparte, una colección de líneas y una regla de pagos propias. La tabla resume esas diferencias. | Tipo | Contraparte en `info` | Colección | Pagos (`info.pagos`) | |---|---|---|---| | `01` Factura | `...Comprador` (quien te compra) | `detalles` con `codigoPrincipal` | Obligatorio | | `03` Liquidación de compra | `...Proveedor` (a quien compras) | `detalles` con `codigoPrincipal` | Obligatorio | | `04` Nota de crédito | `...Comprador` de la factura original | `detalles` con `codigoInterno` | No se envía | | `05` Nota de débito | `...Comprador` | `motivos` | Obligatorio | | `06` Guía de remisión | Transportista | `destinatarios` | No se envía | | `07` Comprobante de retención | `...SujetoRetenido` | `docsSustento` | Dentro del sustento | ### Secuencial automático El secuencial es el contador del comprobante dentro de una serie, y puedes dejar que te lo asignemos o enviar el tuyo. Una serie es la combinación de RUC + `estab` + `ptoEmi` + tipo de comprobante + ambiente: cada serie lleva su propio contador, y el de pruebas es independiente del de producción. | Lo que envías en `secuencial` | Qué número recibe el comprobante | |---|---| | Nada (omites el campo), `""` o solo ceros (`"000000000"`) | Te asignamos el siguiente número libre de la serie. Te recomendamos esta opción, porque no necesitas llevar el contador en tu sistema. | | Un número (`"124"` o `"000000124"`) | Usamos ese número, completado a 9 dígitos. | Para conocer el número asignado, búscalo en el seguimiento, que lo devuelve en `numeroDocumento` (`002-001-000000124`). La `claveAcceso` que trae el seguimiento, cuando el comprobante ya la tiene, también contiene el secuencial. > [!NOTE] > Te recomendamos usar un solo modo por serie. Si mezclas números propios con el automático, el > automático continúa desde el mayor número usado y tus números propios pueden > chocar con uno ya emitido; en ese caso la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`). ### `origenReferencia` y `referenciaExterna` Son los identificadores de **tu** sistema. Con ellos puedes encontrar la operación desde tu ERP, evitar emitir dos veces el mismo documento y cruzar el comprobante con tu registro contable. | Campo | Para qué sirve | Formato | Ejemplos | |---|---|---|---| | `origenReferencia` | Nombra el sistema o módulo que emite. Usa siempre el mismo valor desde el mismo sistema. | 1 a 64 caracteres: letras y dígitos ASCII y `-` `_` `.` `:` `/`. Sin espacios. | `MiERP`, `tienda-web`, `pos.local-03` | | `referenciaExterna` | Identifica el documento dentro de ese sistema, como tu número interno de factura, pedido o nota. | 1 a 128 caracteres, con el mismo alfabeto. | `FACTURA-2026-0001`, `PED/2026/10/0457`, `NC-00031` | La pareja `origenReferencia` + `referenciaExterna` es única por contribuyente emisor y por ambiente, y vale para todas las API Key de tu integración: dos RUC de tu integración pueden usar la misma referencia. Si envías la misma pareja con el **mismo** cuerpo, la API la trata como un reintento y responde 202 con la misma operación. Si la envías con **otro** cuerpo, responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Por eso, para corregir un comprobante rechazado, usa una `referenciaExterna` nueva, por ejemplo `FACTURA-2026-0001-R1`. ## Reglas de formato Cada dato del comprobante tiene un formato fijo, y la API responde 422 a cualquier valor que no lo cumpla. | Dato | Formato | Ejemplo correcto | Error común | |---|---|---|---| | Importes (`total`, `valor`, `baseImponible`...) | Número JSON con punto decimal y como máximo 2 decimales. | `52.44` | `"52,44"` o `52.444` | | `cantidad`, `precioUnitario` | Número JSON, hasta 6 decimales. | `1.0112` | `1.0112345` | | `tarifa` | Número JSON de 0 a 99.99, hasta 2 decimales, igual a la tarifa del `codigoPorcentaje` en el catálogo del SRI. | `15` | `0.15` (es porcentaje, no fracción) | | Códigos (`codigoPorcentaje`, `formaPago`, tipos de identificación) | Cadena JSON. | `"01"` | `1` (número) | | Identificaciones (`ruc`, `identificacionComprador`) | Cadena de dígitos. | `"0123456789"` | `123456789` (pierde el cero inicial) | | Fechas fiscales (`fechaEmision`, `fechaEmisionDocSustento`) | `dd/MM/yyyy`, del 01/01/2000 al 31/12/2099. Envía en `fechaEmision` la fecha de hoy, porque, salvo en la retención, el comprobante autorizado lleva la fecha del día en que se procesa aunque envíes otra. | `"07/10/2026"` | `"2026-10-07"` | | Periodo fiscal (retención) | `MM/yyyy`. | `"10/2026"` | `"2026-10"` | | Número de un documento (`numDocModificado`) | `ddd-ddd-ddddddddd`. | `"002-001-000000123"` | `"123"` (solo el secuencial) | | Textos | Sin caracteres de control, como saltos de línea o tabuladores, y dentro del máximo de cada campo, que indica la guía de cada tipo. Ningún texto supera 500 caracteres. | `"CONSULTORIA MENSUAL"` | Texto vacío o solo espacios en un campo obligatorio | | Campos de cada objeto | Exactamente los nombres documentados, una sola vez. | `"precioUnitario"` | Un campo desconocido o repetido, que la API rechaza con un 422 | Un número obligatorio que omites no se toma como cero: la API responde 422 con `Campo obligatorio.` Por eso, cuando el valor es cero, envía `0` de forma explícita. ## Cómo calcular los totales Esta sección cuadra paso a paso los totales de una factura con tres líneas: una con descuento, una con un precio de 4 decimales y una con IVA 0 %. Las reglas son las mismas para la liquidación de compra y, sin propina ni pagos, para la nota de crédito. ### Reglas | Valor | Fórmula | Redondeo | |---|---|---| | `precioTotalSinImpuesto` de la línea | `cantidad x precioUnitario - descuento` | A 2 decimales. | | `descuento` de la línea | Importe en dólares, no porcentaje. Un 10 % sobre 37.50 se envía como `3.75`. | Ya con 2 decimales. | | `baseImponible` del IVA de la línea | Igual a `precioTotalSinImpuesto` (más el ICE de la línea, si lo hay). | 2 decimales. | | `valor` del IVA de la línea | `(cantidad x precioUnitario - descuento) x tarifa / 100`, calculado con la base **sin redondear**. | A 2 decimales; el `5` sube (`0.455` -> `0.46`). | | `totalConImpuestos[]` (cabecera) | Una fila por cada pareja `codigo` + `codigoPorcentaje`: `baseImponible` = suma de las bases de esas líneas; `valor` = suma de los `valor` de esas líneas. | Suma, sin recalcular. Máximo 2 filas. | | `totalSinImpuestos` | Suma de `precioTotalSinImpuesto` de todas las líneas (ya con el descuento restado). | Suma. | | `totalDescuento` | Suma de `descuento` de todas las líneas. | Suma. | | `importeTotal` | `totalSinImpuestos` + suma de los IVA + suma de los ICE + `propina`. | Suma. | | `pagos[].total` | La suma de todos los pagos es igual a `importeTotal`. | Suma. | Calcula todos los valores en tu sistema antes de enviarlos. La API **no calcula ni corrige** ninguno: compara lo que envías con estas fórmulas y, si algo no cuadra al centavo, responde 422. ### Paso 1: cada línea | Línea | Cantidad x precio | Descuento | `precioTotalSinImpuesto` | Tarifa | IVA (`valor`) | |---|---|---|---|---|---| | 1. Consultoría | 3 x 12.50 = 37.50 | 2.50 | 37.50 - 2.50 = **35.00** | 15 % (`codigoPorcentaje` `4`) | 35.00 x 15 / 100 = **5.25** | | 2. Repuesto | 3 x 1.0112 = 3.0336 | 0 | 3.0336 -> **3.03** | 15 % (`4`) | 3.0336 x 15 / 100 = 0.45504 -> **0.46** | | 3. Libro | 2 x 4.35 = 8.70 | 0 | **8.70** | 0 % (`0`) | **0** | En la línea 2, el IVA se calcula sobre 3.0336, la base sin redondear, y da 0.46. Si lo calcularas sobre 3.03 daría 0.45, y la API respondería `Valor de impuesto no coincide con base y tasa.` ### Paso 2: impuestos de cabecera Agrupa las líneas por `codigo` + `codigoPorcentaje` y suma sus bases y sus valores. | Grupo | `baseImponible` | `valor` | |---|---|---| | IVA 15 % (`2` + `4`) | 35.00 + 3.03 = **38.03** | 5.25 + 0.46 = **5.71** | | IVA 0 % (`2` + `0`) | **8.70** | **0** | El `valor` de cabecera es la suma de los valores de las líneas, 5.71, y no el 15 % de 38.03, que daría 5.70. ### Paso 3: totales y pagos | Campo | Cálculo | Valor | |---|---|---| | `totalSinImpuestos` | 35.00 + 3.03 + 8.70 | **46.73** | | `totalDescuento` | 2.50 + 0 + 0 | **2.50** | | `propina` | Sin propina | **0** | | `importeTotal` | 46.73 + 5.71 + 0 | **52.44** | | `pagos` | 20.00 en efectivo (`01`) + 32.44 con tarjeta de crédito (`19`) | **52.44** | ### El comprobante completo Este es el comprobante con los totales del ejemplo. Guárdalo como `comprobante.json`, porque lo usan los ejemplos de la sección siguiente. ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "direccionComprador": "DIRECCION DE PRUEBAS", "totalSinImpuestos": 46.73, "totalDescuento": 2.50, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 38.03, "valor": 5.71 }, { "codigo": "2", "codigoPorcentaje": "0", "tarifa": 0, "baseImponible": 8.70, "valor": 0 } ], "propina": 0, "importeTotal": 52.44, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 20.00 }, { "formaPago": "19", "total": 32.44 } ] }, "detalles": [ { "codigoPrincipal": "SERV-001", "descripcion": "CONSULTORIA", "cantidad": 3, "precioUnitario": 12.50, "descuento": 2.50, "precioTotalSinImpuesto": 35.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 35.00, "valor": 5.25 } ] }, { "codigoPrincipal": "REP-002", "descripcion": "REPUESTO", "cantidad": 3, "precioUnitario": 1.0112, "descuento": 0, "precioTotalSinImpuesto": 3.03, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 3.03, "valor": 0.46 } ] }, { "codigoPrincipal": "LIB-003", "descripcion": "LIBRO", "cantidad": 2, "precioUnitario": 4.35, "descuento": 0, "precioTotalSinImpuesto": 8.70, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "0", "tarifa": 0, "baseImponible": 8.70, "valor": 0 } ] } ], "infoAdicional": [ { "nombre": "Pedido", "valor": "PED-2026-0457" } ] } ``` El comprobante no lleva `secuencial`, así que te asignamos el siguiente número de la serie 002-001. Los códigos de tarifa están en [Catálogos: tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva) y los de pago en [Catálogos: formas de pago](/v1/guias/catalogos#formas-de-pago). ## Ejemplo de emisión Con el JSON de [El comprobante completo](#el-comprobante-completo) guardado como `comprobante.json`, ejecuta uno de estos ejemplos. Todos envían la misma `Idempotency-Key`, así que si repites la petición no se emite un segundo comprobante. ```bash curl -s -i -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: FACTURA-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas"); peticion.Headers.Add("Idempotency-Key", "FACTURA-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "FACTURA-2026-0001", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'FACTURA-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: FACTURA-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "FACTURA-2026-0001") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; // client: EcuafactClient creado con tu API Key (ver SDK .NET) // comprobante: FacturaRequest con la Estructura del comprobante EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001"); Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado} / codEstado: {resultado.Admission.CodEstado}"); ``` ```python-sdk from ecuafact import EcuafactClient # client: EcuafactClient creado con tu API Key (ver SDK Python) # comprobante: FacturaRequest con la Estructura del comprobante resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001") print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado} / codEstado: {resultado.admission.cod_estado}") ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; // client: EcuafactClient creado con tu API Key (ver SDK Node.js) // comprobante: FacturaRequest con la Estructura del comprobante const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001"); console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado} / codEstado: ${resultado.admission.codEstado}`); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001'); echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . ' / codEstado: ' . $resultado->admission->codEstado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EmisionResultado; // client: EcuafactClient creado con tu API Key (ver SDK Java) // comprobante: FacturaRequest con la Estructura del comprobante EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001"); System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado() + " / codEstado: " + resultado.admission().codEstado()); ``` ```bash-cli # Resultado esperado: una fila con el estado recibido y el idOperacion de la emisión. ecuafact emitir comprobante.json --entorno sandbox ``` Si no le pasas la `Idempotency-Key`, el SDK la genera por ti y la devuelve en `EmisionResultado`. Guárdala, porque debes reutilizarla en cualquier reintento. ## Respuesta La API responde 202 Accepted con este cuerpo, que tiene la misma forma del [seguimiento de la operación](/v1/guias/consulta-operacion#respuesta): ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "002-001-000000124", "referenciaExterna": "FACTURA-2026-0001", "claveAcceso": null, "fhRecibido": "2026-11-16T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización del SRI. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu sistema debe aceptar los dos valores. | | `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía. | | `idOperacion` | string (UUID) | Identificador de la operación. Guárdalo junto a tu documento, porque lo necesitas para el seguimiento y llega en el webhook. | | `urlEstado` | string | URL completa del seguimiento, `https:///v1/operaciones/{idOperacion}`. Puedes llamarla tal como viene. | | `ambiente` | number | `1` para pruebas y `2` para producción, según la URL que llamaste. | | `tipoDocumento` | string | Tipo de comprobante: `01`, `03`, `04`, `05`, `06` o `07`. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`. Si omitiste el `secuencial`, aquí ves el que te asignamos. | | `referenciaExterna` | string o `null` | La `referenciaExterna` que enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001 y viene con el 1002. Si es `null`, la obtienes después en el seguimiento o en el webhook. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con la zona horaria de Ecuador. | | `fhAutorizacion` | string o `null` | Fecha y hora de autorización; en el 202 de una emisión nueva es `null`. | El campo `msgError` no aparece porque la emisión no tiene error. Te recomendamos leer el 202 con la misma lógica que el seguimiento: decide con `estado` y `codEstado` y trata la `claveAcceso` como opcional mientras el `estado` sea `recibido`. | Cabecera | Descripción | |---|---| | `Location` | La misma URL completa que `urlEstado`. | | `X-Correlation-Id` | Identificador de la petición. Inclúyelo si pides soporte. | Un reintento con la misma `Idempotency-Key` y el mismo cuerpo, o con la misma `origenReferencia` + `referenciaExterna` y el mismo cuerpo, responde un 202 con el mismo `idOperacion` y el estado actual de esa operación, sin crear otro comprobante. El resultado actual de esa operación lo ves siempre en el seguimiento. El 202 puede traer `autorizado` (2001) si la emisión directa ya conoce el resultado; en ese caso no sigas esperando. Si ya conoce un rechazo definitivo, `rechazado` (3xxx, con el detalle del SRI en `errores`) o `rechazo_configuracion` (4xxx), la respuesta no es un 202 sino un 422 con el mismo cuerpo de la operación: `estado`, `codEstado`, `msgError`, `errores`, `idOperacion` y `urlEstado`. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo devuelve el mismo 422; corrige la causa y emite con una `referenciaExterna` nueva. Cuando el 202 trae `recibido`, el comprobante todavía no está autorizado; después de recibirlo, sigue estos pasos: 1. Guarda `idOperacion` junto a tu documento. 2. Espera el [webhook](/v1/guias/webhooks) (`document.authorized`, `document.rejected` o `document.failed`) o consulta [`GET /v1/operaciones/{idOperacion}`](/v1/guias/consulta-operacion) mientras su `estado` sea `recibido`. 3. Con `autorizado`, descarga el [RIDE](/v1/guias/consulta-ride) o el [XML](/v1/guias/consulta-xml). Con cualquier otro estado final, lee el `codEstado` y el detalle de `errores`, corrige la causa y reenvía el comprobante como se explica en [Reintentos y duplicados](#reintentos-y-duplicados). Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo, y uno cancelado lo libera. Una solicitud mal formada (400) no consume cupo, y un 422 por validación consume 1 documento como intento. El detalle está en [Consumo y cuotas](/v1/guias/consumo). ## Validar sin emitir Antes de emitir puedes comprobar que un comprobante está bien armado. La validación aplica las mismas reglas que la emisión: la estructura, los formatos, los totales, los impuestos y los pagos, que `infoTributaria.ruc` corresponda al contribuyente de la ruta y que el contribuyente y el tipo de comprobante estén habilitados para tu API Key. No emite nada, no consume cupo ni usa un número de la serie, y no necesita `Idempotency-Key`. Si tu cliente la envía siempre, la validación la ignora: no la valida ni la guarda, y reutilizarla con otro cuerpo no produce un 409. Cada validación cuenta para tu [límite de solicitudes](/v1/guias/limite-de-request) por minuto. Te sirve sobre todo cuando generas los comprobantes de forma automática, por ejemplo desde un archivo o con un asistente de IA: validas el lote completo, corriges lo que falle y emites después solo lo que pasó. La ruta de validación es la de emisión del tipo con `/validar` al final. Para una factura: ``` POST /v1/contribuyentes/{identificacion}/facturas/validar X-Api-Key: Content-Type: application/json ``` El cuerpo y sus límites son los mismos de [Endpoint](#endpoint), sin la cabecera `Idempotency-Key`. Si el comprobante cumple todas las reglas, la API responde 200 OK con este cuerpo: ```json { "valido": true, "errores": [] } ``` | Campo | Tipo | Descripción | |---|---|---| | `valido` | boolean | `true` cuando el comprobante cumple todas las reglas de la emisión. | | `errores` | array de string | Viene siempre y, en una validación correcta, es una lista vacía. | Si no las cumple, responde el mismo código que daría la emisión, con la forma de error de toda la API (`estado`, `codEstado`, `msgError` y `errores`): un 422 con el `codEstado` 3002 (`comprobante_invalido`) y hasta 20 problemas en `errores`, como se explica en [Errores de validación](#errores-de-validacion), o un 403 con el `codEstado` 3011 (`acceso_denegado`) si el contribuyente, su RUC o el tipo de comprobante no están habilitados para tu API Key. Un 200 significa que, con el contenido que enviaste, la emisión no tendrá errores de validación. La validación no comprueba tu cupo ni si ya emitiste ese comprobante, así que al emitir todavía puedes recibir un 429 con el `codEstado` 4004 si no tienes un paquete vigente con saldo, o la respuesta de un reintento si ya usaste esa `Idempotency-Key`. Tampoco es una autorización del SRI: el resultado fiscal llega solo después de emitir. Estos ejemplos validan el `comprobante.json` de [Ejemplo de emisión](#ejemplo-de-emision): ```bash curl -s -X POST "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar" -H "X-Api-Key: $ECUAFACT_API_KEY" -H "Content-Type: application/json" -d @comprobante.json # 200 OK con valido en true si cumple todas las reglas; si no, el error de la emisión. ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var contenido = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.PostAsync("/v1/contribuyentes/0123456789001/facturas/validar", contenido); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como validar.mjs y ejecuta: node validar.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```bash-cli # Resultado esperado: una fila con el estado valido, o invalido con el error de la API. ecuafact validar comprobante.json --entorno sandbox ``` ## Errores de validación Cuando una emisión no pasa la validación, la API responde con el primer problema que encontró, así que cada respuesta te dice qué corregir. Si el cuerpo tiene errores y además falta la cabecera `Idempotency-Key`, primero recibes el error del cuerpo. Un 400 con el `codEstado` 3003 (`solicitud_invalida`) significa que la **petición** está mal formada, porque el JSON está roto o la cabecera `Idempotency-Key` falta o no es válida. Un 422 con el `codEstado` 3002 (`comprobante_invalido`) significa que la API entendió la petición, pero el **comprobante** no cumple una regla. Un 400 **no consume cupo**; un 422 **consume 1 documento como intento**. Ninguno de los dos usa un número de la serie. Corrige el dato y reenvía con la misma `Idempotency-Key`. Así se ve un error de validación. Tiene la misma forma de la respuesta 202, con `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`, porque no se creó ninguna operación: ```json { "estado": "rechazado", "codEstado": 3002, "msgError": "El comprobante no cumple las validaciones.", "errores": [ "$.info.pagos[0].unidadTiempo: Obligatoria cuando hay plazo." ], "idOperacion": null, "urlEstado": null, "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": null, "referenciaExterna": "FACTURA-2026-0001", "claveAcceso": null, "fhRecibido": null, "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `rechazado` en los errores de validación. | | `codEstado` | number | Código estable para programar, como 3003 (`solicitud_invalida`) o 3002 (`comprobante_invalido`). | | `msgError` | string | Descripción general y fija del código. Puedes mostrarla, pero no decidas con ella. | | `errores` | array de string | Viene siempre. En 3002 (`comprobante_invalido`) trae hasta 20 mensajes, uno por problema, cada uno con la ruta del campo y, cuando corresponde, la posición de la línea o del impuesto (`$.info.pagos[0].unidadTiempo`, `$.detalles[3].impuestos[0].valor`). En 3003 (`solicitud_invalida`) trae el detalle de los parámetros o del cuerpo que no se pudo leer; puede ser más de uno. En los demás errores es una lista vacía. Corrige todos los que puedas y reenvía; los que no se hayan podido validar aparecerán en la siguiente respuesta. | | `ambiente`, `tipoDocumento` y `referenciaExterna` | | Vienen con el valor de tu petición cuando la API pudo leerlo; si no, son `null`. | ### Mensajes de validación frecuentes Estos son los mensajes de `errores` que aparecen con más frecuencia al emitir cualquier tipo de comprobante. | Mensaje (en `errores`) | Causa | Qué hacer | |---|---|---| | `Campo no soportado en este contrato.` | Un campo que la API no conoce en ese objeto, como `claveAcceso`, `ambiente`, un campo de `info`, una colección o un código de línea de otro tipo (`motivos` o `codigoInterno` en una factura), o un nombre mal escrito. | Quita el campo o corrige su nombre; envía solo los campos y la colección de la guía del tipo, según [Qué cambia por tipo](#que-cambia-por-tipo). | | `Valor o tipo inválido.` | Un tipo JSON incorrecto: un número donde va una cadena (`"estab": 2`) o un texto donde va un número. A veces añade qué se esperaba, por ejemplo `Valor o tipo inválido: se esperaba texto.` | Envía los códigos como cadena y los importes como número. | | `Campo obligatorio.` / `Texto vacio o longitud excedida.` | Falta un campo obligatorio, está vacío o supera su largo. | Completa el campo indicado en la ruta. | | `Numero fuera de rango.` | Un número negativo o demasiado grande. | Envía importes positivos: la nota de crédito y la retención también llevan valores positivos. | | `La creación de este tipo requiere un contribuyente identificado.` | Tipo de identificación `07` (consumidor final) en un tipo distinto de la factura. | Identifica a la contraparte con RUC, cédula, pasaporte o identificación del exterior. | | `Para una factura mayor a $50, seleccione un cliente con cedula, RUC o pasaporte...` | Una factura a consumidor final (`07`) con `importeTotal` mayor que 50. | Identifica al comprador con RUC, cédula o pasaporte. | | `Lista vacia, invalida o demasiado extensa.` | Falta una lista obligatoria (`detalles`, `pagos`, `totalConImpuestos`) o supera su máximo. | Envía al menos un elemento y respeta el máximo. | | `Use dd/MM/yyyy, como el SRI.` | Fecha en otro formato. | Usa `07/10/2026`. | | `El RUC no corresponde al contribuyente del contexto.` | `infoTributaria.ruc` no corresponde a la `identificacion` de la ruta. | Usa el RUC completo del contribuyente de la ruta. | | `Subtotal del detalle no coincide...` | `precioTotalSinImpuesto` distinto de `cantidad x precioUnitario - descuento` redondeado. | Recalcula la línea. | | `Valor de impuesto no coincide con base y tasa.` | El IVA de una línea no es la base sin redondear por la tarifa, redondeado a 2 decimales. | Calcula el IVA antes de redondear la base. | | `Base IVA debe incluir subtotal e ICE.` | La `baseImponible` del IVA es distinta de `precioTotalSinImpuesto` más el ICE de la línea. | Usa el subtotal de la línea como base. | | `Base o valor de impuestos no coincide con detalles.` | Una fila de `totalConImpuestos` no es la suma de sus líneas. | Suma bases y valores por `codigo` + `codigoPorcentaje`. | | `Los impuestos de cabecera no corresponden a los detalles.` | Falta o sobra una fila en `totalConImpuestos`, o hay dos filas con el mismo `codigo` + `codigoPorcentaje`. | Envía exactamente una fila por grupo de las líneas. | | `Totales no coinciden con detalles.` | `totalSinImpuestos`, `totalDescuento` o la suma de IVA no cuadra con las líneas. | Suma de nuevo las líneas. | | `total no coincide con subtotal + IVA + ICE + propina.` | El `importeTotal`, o el `valorModificacion` en la nota de crédito, está mal calculado. | Aplica la fórmula del total. | | `Pagos no coinciden con total.` | La suma de `pagos[].total` es distinta de `importeTotal`. | Ajusta los pagos al total. | | `...importe no admitido; no se redondea silenciosamente.` | Un importe con más de 2 decimales, o cantidad o precio con más de 6. | Redondea en tu sistema antes de enviar. | Cada guía de tipo agrega los mensajes propios de ese comprobante. ## Reintentos y duplicados Con la `Idempotency-Key` puedes reintentar un envío sin emitir dos veces el mismo comprobante. Usa un valor estable por intención, como tu número interno del documento (`FACTURA-2026-0001`) o un UUID v4 que guardas junto al documento **antes** de enviarlo. La API recuerda la clave durante 7 días, por integración y por ambiente. | Situación | Qué envías | Resultado | Qué hacer | |---|---|---|---| | Timeout, error de red o 5xx sin respuesta clara | La misma `Idempotency-Key` y el mismo cuerpo. | 202 con el mismo `idOperacion` si el primer intento llegó, o con una operación nueva si nunca llegó. | Continúa con el seguimiento de ese `idOperacion`. | | Reenvío accidental del mismo documento | La misma `Idempotency-Key` y el mismo cuerpo. | 202 con el mismo `idOperacion`. | No hagas nada; no se emitió otro comprobante. | | Misma `Idempotency-Key` con un cuerpo distinto | La clave repetida y el cuerpo cambiado. | 409 con el `codEstado` 3005 (`conflicto_idempotencia`). | Si es otro documento, usa otra clave. Si es una corrección, sigue la fila del rechazo que corresponda. | | Misma `origenReferencia` + `referenciaExterna` con un cuerpo distinto, o con otro tipo de comprobante | Una clave nueva y una referencia que ya usó otro comprobante. | 409 con el `codEstado` 3005 (`conflicto_idempotencia`). | Usa una `referenciaExterna` nueva para el documento corregido. | | Número (`estab-ptoEmi-secuencial`) de un comprobante autorizado, pendiente o rechazado por el SRI | Un `secuencial` propio que ya se usó. | 409 con el `codEstado` 3004 (`comprobante_duplicado`). | No reenvíes, porque ese número ya existe. Si el comprobante anterior fue rechazado por el SRI, emite con un secuencial nuevo; omite `secuencial` para que se asigne el siguiente. | | Corregir un comprobante que no se emitió: `estado` `rechazado` con el `codEstado` 3002, `rechazo_configuracion` con cualquier código 4xxx, o `error` con el 5006 (`entrega_no_posible`) | El cuerpo corregido, una **nueva** `Idempotency-Key`, una **nueva** `referenciaExterna` y, para conservar el número, el mismo `estab`, `ptoEmi` y `secuencial` en `infoTributaria`. | 202, que puede traer el mismo `idOperacion`. Si corriges el contenido tras un rechazo, cuenta como otro envío y consume 1 documento; si reenvías con el mismo número tras un `error` 5006, no consume otro, como se explica en [Consumo y cuotas](/v1/guias/consumo). | Sigue la operación como siempre. | | Reenviar una operación `cancelado` | Una **nueva** `Idempotency-Key` y una **nueva** `referenciaExterna`; puedes usar el mismo número. | 202 con `estado` en `recibido` y el `codEstado` 1001 o 1002. | Sigue la operación. Si envías la misma `referenciaExterna` y el mismo cuerpo, la API devuelve la operación cancelada y no emite. | | Corregir un comprobante rechazado por el SRI (`estado` `rechazado` con el `codEstado` 3001) | El cuerpo corregido, una **nueva** `Idempotency-Key` y una **nueva** `referenciaExterna`, sin `secuencial` para que se asigne automáticamente. | 202 con una operación nueva. | Emite con un secuencial nuevo, porque si reutilizas el mismo número la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`). | | `estado` `error` con el `codEstado` 5007 (`resultado_no_confirmado`) o 5001 (`error_interno`) | Nada todavía. | - | No reemitas, porque el comprobante podría existir. Búscalo en el seguimiento y escribe a [soporte](/v1/guias/errores#como-pedir-soporte) con el `idOperacion`. | Si omitiste el `secuencial` y quieres conservar el número al reenviar, búscalo en el `numeroDocumento` de la respuesta 202 o del seguimiento; si no lo necesitas, deja que se asigne el siguiente. > [!WARNING] > No generes una `Idempotency-Key` nueva para reintentar un envío cuyo resultado > no conoces (timeout). Si el primer intento llegó, la clave nueva emite un > segundo comprobante, con otro número y otro cupo consumido. ## Estados de este endpoint Esta tabla reúne todas las respuestas posibles de la emisión. Todas, incluidos los errores, traen la forma de la respuesta 202 que se explica en [Respuesta](#respuesta). | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 1001, 1002 o 2001 | 202 | La API recibió el comprobante, o reintentaste con la misma `Idempotency-Key` o la misma referencia y el mismo cuerpo. El 2001 indica que la autorización ya se conoce. | Guarda `idOperacion` y sigue la operación; un reintento no emite otro comprobante y trae el estado actual. | | 3003 (`solicitud_invalida`) | 400 | El JSON o el XML está mal formado, o la `Idempotency-Key` falta o no es válida. | Corrige la petición y reenvía. | | 3002 (`comprobante_invalido`) | 422 | El comprobante no cumple una regla de estructura o fiscal; el detalle viene en `errores`. | Corrige el campo indicado. Consume 1 documento como intento. | | 3xxx o 4xxx | 422 | La emisión directa ya conoce un rechazo definitivo (`rechazado` o `rechazo_configuracion`); el cuerpo trae el `codEstado`, el `msgError` y el detalle en `errores`. | Corrige la causa según el `codEstado` y emite con una `referenciaExterna` nueva. | | 3006 (`cuerpo_excedido`) | 413 | El cuerpo supera 2 MiB. | Reduce el cuerpo, con menos líneas o textos más cortos. | | 3004 (`comprobante_duplicado`) | 409 | Ya existe un comprobante con ese número (`estab`-`ptoEmi`-`secuencial`) autorizado, pendiente o rechazado por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo (omite `secuencial` para que se asigne el siguiente). | | 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key`, o la misma `origenReferencia` + `referenciaExterna`, con otro cuerpo. | Reutiliza el cuerpo original o usa una clave y referencia nuevas para el documento nuevo. | | 4004 (`cupo_agotado`) | 429 | No quedan documentos en tus paquetes vigentes. | Compra un paquete en el portal y no reintentes en bucle. Revisa [Consumo](/v1/guias/consumo). | | 3009 (`credenciales_invalidas`) | 401 | La API Key falta o no es válida. | Revisa la API Key. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o revisa proxies o balanceadores entre tu sistema y la API. | | 3011 (`acceso_denegado`) | 403 | El contribuyente o el tipo de comprobante no están habilitados para tu integración. | Revisa la `identificacion` y los `tiposComprobante` del contexto. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera lo que indica `Retry-After` y reintenta con la misma `Idempotency-Key`. Es el único 429 que se reintenta; el 4004 no. | | 3003 (`solicitud_invalida`) | 415 | El `Content-Type` no es `application/json`, `application/xml` ni `text/xml`, por ejemplo porque falta la cabecera. | Envía el `Content-Type` que corresponda al cuerpo. | | 5001 (`error_interno`) / 5002 (`servicio_no_disponible`) | 500 / 503 | Ocurrió un error interno o el servicio no está disponible. | Reintenta con la misma `Idempotency-Key` y el mismo cuerpo. | El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Factura](/v1/guias/emision-01): campos de la factura y ejemplos con varias tarifas, descuento y pago a crédito. - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta el resultado del SRI con tu `idOperacion`. - [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar. - [Errores](/v1/guias/errores#catalogo-de-codestado): catálogo de `codEstado` y si se reintenta o se corrige. --- # Factura Emite una factura, el comprobante con el que cobras la venta de un bien o un servicio, con sus impuestos, totales y formas de pago. La factura es el comprobante que más vas a emitir. Esta guía te da un ejemplo mínimo listo para enviar, describe cada campo de su estructura con las reglas que valida la API y reúne ejemplos con varias tarifas de IVA, descuento, pago a crédito e ICE. Las cabeceras, el [secuencial](/v1/guias/glosario) automático y las reglas comunes a todos los tipos están en [Comprobantes electrónicos](/v1/guias/emision). Aquí encuentras solo lo propio de la factura. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan > `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba). Envías la factura a `POST /v1/contribuyentes/{identificacion}/facturas`. El tipo de comprobante lo fija la ruta, así que el cuerpo no lleva `infoTributaria.tipoDocumento`. ``` POST /v1/contribuyentes/{identificacion}/facturas ``` Para revisar el cuerpo sin emitir, usa `POST /v1/contribuyentes/{identificacion}/facturas/validar`; aplica las mismas reglas y su respuesta se describe en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). ## Cuándo la emites Emite una factura en situaciones como estas: - Vendes un producto en tu tienda física o en línea. - Prestas un servicio, como una consultoría, un mantenimiento o una suscripción mensual. - Vendes a crédito. Emites la factura al momento de la venta e informas el plazo en `pagos`. - Vendes a un consumidor que no da sus datos. En ese caso facturas a "consumidor final", pero solo hasta USD 50.00 de `importeTotal`. Si necesitas devolver dinero o anular una factura ya autorizada, no la edites: emite una [nota de crédito](/v1/guias/emision-04). ## Ejemplo mínimo Este ejemplo factura una línea de servicio de 100.00 con IVA 15 %, pagada en efectivo. Guarda el JSON como `comprobante.json`, porque lo usan los ejemplos de [Envío](#envio). ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0002", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "direccionComprador": "DIRECCION DE PRUEBAS", "totalSinImpuestos": 100.00, "totalDescuento": 0, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 100.00, "valor": 15.00 } ], "propina": 0, "importeTotal": 115.00, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 115.00 } ] }, "detalles": [ { "codigoPrincipal": "SERV-001", "descripcion": "SERVICIO DE MANTENIMIENTO", "cantidad": 1, "precioUnitario": 100.00, "descuento": 0, "precioTotalSinImpuesto": 100.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 100.00, "valor": 15.00 } ] } ], "infoAdicional": [ { "nombre": "Orden", "valor": "OC-1001" } ] } ``` La tabla muestra cómo se calcula cada total del ejemplo. | Campo | Cálculo | Valor | |---|---|---| | `detalles[0].precioTotalSinImpuesto` | 1 x 100.00 - 0 | 100.00 | | `detalles[0].impuestos[0].valor` | 100.00 x 15 / 100 | 15.00 | | `totalConImpuestos[0]` | Suma de la única línea con IVA 15 % (`codigoPorcentaje` `4`) | base 100.00, valor 15.00 | | `totalSinImpuestos` | Suma de `precioTotalSinImpuesto` | 100.00 | | `importeTotal` | 100.00 + 15.00 + 0 de propina | 115.00 | | `pagos[0].total` | Toda la factura en efectivo (`01`) | 115.00 | Como el comprobante no lleva `secuencial`, te asignamos el siguiente número de la serie 002-001. El paso a paso con descuentos, varias tarifas y redondeo está en [Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales). ## Envío Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`, FACTURA-2026-0002, así que repetir el envío no emite otra factura. ```bash curl -s -i -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: FACTURA-2026-0002" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas"); peticion.Headers.Add("Idempotency-Key", "FACTURA-2026-0002"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "FACTURA-2026-0002", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'FACTURA-2026-0002', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: FACTURA-2026-0002', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "FACTURA-2026-0002") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; // client: EcuafactClient creado con tu API Key (ver SDK .NET) // comprobante: FacturaRequest con la factura de esta pagina EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0002"); Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}"); ``` ```python-sdk from ecuafact import EcuafactClient # client: EcuafactClient creado con tu API Key (ver SDK Python) # comprobante: FacturaRequest con la factura de esta pagina resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0002") print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}") ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; // client: EcuafactClient creado con tu API Key (ver SDK Node.js) // comprobante: FacturaRequest con la factura de esta pagina const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0002"); console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0002'); echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EmisionResultado; // client: EcuafactClient creado con tu API Key (ver SDK Java) // comprobante: FacturaRequest con la factura de esta pagina EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0002"); System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()); ``` ```bash-cli # Resultado esperado: una fila con el estado recibido y el idOperacion de la factura. ecuafact emitir comprobante.json --entorno sandbox ``` **Resultado esperado.** La API responde 202 con `estado` en `recibido` y un `idOperacion`. Si repites el mismo envío, la respuesta es la misma y trae el mismo `idOperacion`, así que no se emite otra factura. ## Estructura del comprobante El cuerpo de la factura se organiza en bloques, y cada tabla describe uno. ### Raíz | Clave | Tipo | Obligatorio | Regla | |---|---|---|---| | `origenReferencia` | string | Sí | Nombre de tu sistema, de 1 a 64 caracteres entre letras y dígitos ASCII y `-` `_` `.` `:` `/`. | | `referenciaExterna` | string | Sí | Tu número interno del documento, de 1 a 128 caracteres con el mismo alfabeto. | | `infoTributaria` | object | Sí | Identidad del comprobante. Sus campos están en la tabla siguiente. | | `info` | object | Sí | Cabecera de la factura, que se describe más abajo. | | `detalles` | array | Sí | De 1 a 1000 líneas. | | `infoAdicional` | array | No | Hasta 15 objetos `{ "nombre", "valor" }`. | Para qué sirven `origenReferencia` y `referenciaExterna` se explica en [Comprobantes electrónicos](/v1/guias/emision#origenreferencia-y-referenciaexterna). ### `infoTributaria` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `ruc` | string | Sí | RUC completo del emisor, de 13 dígitos; en pruebas, `0123456789001`. | | `estab` | string | Sí | Establecimiento, de hasta 3 dígitos. Se completa con ceros, así que `"2"` se toma como `"002"`. | | `ptoEmi` | string | Sí | Punto de emisión, de hasta 3 dígitos. Se completa con ceros. | | `secuencial` | string | No | Hasta 9 dígitos. Omítelo, o envía `"000000000"`, y te asignamos el siguiente, como se explica en [Secuencial automático](/v1/guias/emision#secuencial-automatico). | No envíes `claveAcceso`: te la asignamos nosotros y la ves en el [seguimiento](/v1/guias/consulta-operacion). ### `info` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `fechaEmision` | string | Sí | `dd/MM/yyyy`. Envía la fecha de hoy, porque el comprobante autorizado lleva la fecha del día en que se procesa. | | `dirEstablecimiento` | string | No | Dirección del establecimiento que vende, hasta 300 caracteres. | | `tipoIdentificacionComprador` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte, `07` consumidor final u `08` identificación del exterior. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). | | `identificacionComprador` | string | Sí | Con `04`, 13 dígitos. Con `05`, 10 dígitos. Con `07`, exactamente `9999999999999`. Con `06` y `08`, hasta 20 caracteres. | | `razonSocialComprador` | string | Sí | Nombre o razón social del comprador, hasta 300 caracteres. Para un consumidor final, envía `CONSUMIDOR FINAL`. | | `direccionComprador` | string | No | Hasta 300 caracteres. | | `telefono` | string | No | Teléfono del comprador, hasta 40 caracteres. | | `correo` | string | No | Correo del comprador al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se toma el valor de un campo de `infoAdicional` llamado `email` o `correo`. | | `totalSinImpuestos` | number | Sí | Suma de `detalles[].precioTotalSinImpuesto`, ya sin descuentos. | | `totalDescuento` | number | Sí | Suma de `detalles[].descuento`. Envía `0` si no hay descuentos. | | `totalConImpuestos` | array | Sí | Una o dos filas, una por cada pareja `codigo` + `codigoPorcentaje` de las líneas. Se describe más abajo. | | `propina` | number | Sí | Propina, con 2 decimales como máximo. Envía `0` si no hay. Se suma al total y no paga IVA. | | `importeTotal` | number | Sí | `totalSinImpuestos` + IVA + ICE + `propina`. | | `moneda` | string | Sí | `DOLAR` o `USD`. | | `pagos` | array | Sí | De 1 a 20 formas de pago, cuya suma es igual a `importeTotal`. Se describe más abajo. | | `guiaRemision` | string | No | Número de la guía de remisión que acompaña la mercadería, con el formato `ddd-ddd-ddddddddd`; otro formato responde 422. | | `placa` | string | No | Placa del vehículo, hasta 20 caracteres. Se usa, por ejemplo, en una venta de combustible. | | `comercioExterior` | string | No | Valor fijo `EXPORTADOR` cuando la factura corresponde a comercio exterior. | | `incoTermFactura` | string | No | Término de negociación internacional (Incoterm) de la factura de exportación, hasta 100 caracteres. | | `lugarIncoTerm` | string | No | Lugar pactado para la entrega según el Incoterm, hasta 300 caracteres. | | `paisOrigen` | string | No | Código del país de origen de la mercadería, según el catálogo de [Países](/v1/guias/catalogos#paises-comercio-exterior). | | `puertoEmbarque` | string | No | Puerto de embarque de la mercadería, hasta 100 caracteres. | | `puertoDestino` | string | No | Puerto de destino de la mercadería, hasta 100 caracteres. | | `paisDestino` | string | No | Código del país de destino de la mercadería, según el catálogo de [Países](/v1/guias/catalogos#paises-comercio-exterior). | | `paisAdquisicion` | string | No | Código del país donde el importador adquirió la mercadería, según el catálogo de [Países](/v1/guias/catalogos#paises-comercio-exterior). | | `incoTermTotalSinImpuestos` | string | No | Incoterm aplicado sobre el total sin impuestos, cuando difiere del de los precios unitarios. | La factura tampoco admite estos campos de `info`: `contribuyenteEspecial`, `obligadoContabilidad`, `totalSubsidio`, `compensaciones`, `fleteInternacional`, `seguroInternacional`, `gastosAduaneros`, `gastosTransporteOtros`, `valorRetIva`, `valorRetRenta`, `retenciones`, `reembolsos`, `codDocReembolso`, `totalComprobantesReembolso`, `totalBaseImponibleReembolso`, `totalImpuestoReembolso`, `infoSustitutivaGuiaRemision`, `otrosRubrosTerceros`, `tipoNegociable` y `maquinaFiscal`, ni los campos de otros tipos de comprobante, como `...Proveedor` o `motivo`. Si envías alguno, la API responde 422 con `Campo no soportado en este contrato.` La API tampoco procesa `unidadMedida` ni `precioSinSubsidio` en `detalles[]`, ni `descuentoAdicional` ni `valorDevolucionIva` en `impuestos[]`. No los envíes, porque la API los rechaza como campos desconocidos. ### `detalles[]` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codigoPrincipal` | string | Sí | Código del producto o servicio en tu sistema, hasta 25 caracteres. | | `codigoAuxiliar` | string | No | Segundo código, como el código de barras, de hasta 25 caracteres. | | `descripcion` | string | Sí | Hasta 300 caracteres. | | `cantidad` | number | Sí | Mayor que 0, hasta 6 decimales. | | `precioUnitario` | number | Sí | Mayor o igual a 0, hasta 6 decimales, sin IVA. | | `descuento` | number | Sí | Importe del descuento de la línea en dólares, no en porcentaje, con 2 decimales como máximo. Envía `0` si no hay. | | `precioTotalSinImpuesto` | number | Sí | `cantidad x precioUnitario - descuento`, redondeado a 2 decimales. | | `impuestos` | array | Sí | Un IVA obligatorio y, como máximo, un ICE. Se describe más abajo. | | `detallesAdicionales` | array | No | Hasta 3 objetos `{ "nombre", "valor" }`, como el color o el número de serie. | No uses `codigoInterno` ni `codigoAdicional` en la factura, porque son de la nota de crédito. Si los envías, la API responde 422 con `Campo no soportado en este contrato.` ### `detalles[].impuestos[]` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codigo` | string | Sí | `"2"` para el IVA, exactamente uno por línea, o `"3"` para el ICE, como máximo uno. Otros impuestos, como el IRBPNR (`"5"`), no se admiten. | | `codigoPorcentaje` | string | Sí | Código de la tarifa, de hasta 4 dígitos. En el IVA, `"4"` es 15 %, `"0"` es 0 %, `"6"` es no objeto y `"7"` es exento. La tabla completa está en [Catálogos: tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva). | | `tarifa` | number | Sí | Porcentaje, por ejemplo `15` y no `0.15`. Con `codigoPorcentaje` `0`, `6` o `7` debe ser `0`; con las demás tarifas de IVA, mayor que 0. | | `baseImponible` | number | Sí | Igual a `precioTotalSinImpuesto` de la línea. En el IVA, más el ICE de la línea si lo hay. | | `valor` | number | Sí | `(cantidad x precioUnitario - descuento) x tarifa / 100` con la base sin redondear, redondeado a 2 decimales. | Envía la pareja exacta del catálogo, por ejemplo `"4"` con `15`. Para el IVA, la API comprueba que el `codigoPorcentaje` exista en el catálogo del SRI y que la `tarifa` sea la de ese código; si no coinciden, responde 422 con `La tarifa no corresponde al codigoPorcentaje del catálogo del SRI.` ### `info.totalConImpuestos[]` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codigo` | string | Sí | Igual al de las líneas del grupo. | | `codigoPorcentaje` | string | Sí | Igual al de las líneas del grupo. | | `tarifa` | number | No | Si lo envías, debe ser igual a la `tarifa` de esas líneas. | | `baseImponible` | number | Sí | Suma de `baseImponible` de las líneas del grupo. | | `valor` | number | Sí | Suma de `valor` de las líneas del grupo, sin recalcularlo sobre la base sumada. | Envía exactamente una fila por cada pareja `codigo` + `codigoPorcentaje` que aparezca en las líneas, y como máximo dos filas. ### `info.pagos[]` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `formaPago` | string | Sí | Código de 2 dígitos, como `"01"` sin utilización del sistema financiero (efectivo), `"19"` tarjeta de crédito o `"20"` otros con utilización del sistema financiero (transferencia). La tabla completa está en [Catálogos: formas de pago](/v1/guias/catalogos#formas-de-pago). | | `total` | number | Sí | Monto pagado con esta forma, con 2 decimales como máximo. | | `plazo` | number | No | Plazo de pago, como número entero mayor o igual a 0. Omítelo o envía `0` en los pagos de contado. | | `unidadTiempo` | string | Condicional | Obligatoria si `plazo` es mayor que 0. Admite `dias`, `meses` o `anios`, de [Catálogos](/v1/guias/catalogos#unidades-de-tiempo), con hasta 20 caracteres. Si la omites con plazo 0, se asume `dias`. | ### `infoAdicional[]` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `nombre` | string | Sí | Etiqueta que se imprime en el RIDE, hasta 300 caracteres. | | `valor` | string | Sí | Valor, hasta 300 caracteres. | ## Reglas de cálculo y validaciones Si la factura incumple una de estas reglas, la API responde 422 con el código `comprobante_invalido` y el detalle en `errores`. Las reglas comunes de totales están en [Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales). | Regla | Mensaje (en `errores`) | Qué hacer | |---|---|---| | En cada línea, `precioTotalSinImpuesto` es `cantidad x precioUnitario - descuento` redondeado. | `Subtotal del detalle no coincide...` | Recalcula la línea. | | El IVA de la línea se calcula sobre la base sin redondear. | `Valor de impuesto no coincide con base y tasa.` | Calcula `valor` antes de redondear la base. | | La cabecera lleva una fila por grupo, con las sumas exactas. | `Base o valor de impuestos no coincide con detalles.` | Suma bases y valores por grupo. | | `totalSinImpuestos`, `totalDescuento` y el IVA cuadran con las líneas. | `Totales no coinciden con detalles.` | Suma de nuevo las líneas. | | `importeTotal` es subtotal + IVA + ICE + propina. | `total no coincide con subtotal + IVA + ICE + propina.` | Corrige `importeTotal`. | | La suma de `pagos` es igual a `importeTotal`. | `Pagos no coinciden con total.` | Ajusta los pagos. | | `unidadTiempo` es obligatoria cuando hay plazo. | `Obligatoria cuando hay plazo.` | Agrega `"unidadTiempo": "dias"`. | | `plazo` es un número entero. | `Plazo entero fuera de rango.` | Envía `30`, no `30.5`. | | Cada línea lleva un IVA y como máximo un ICE. | `Se admite un IVA y opcionalmente ICE porcentual.` | Deja un solo impuesto `"2"` por línea. | | La tarifa es coherente con el tipo de IVA. | `IVA gravado requiere tasa positiva.` / `IVA 0 requiere tasa 0.` / `No objeto requiere tasa 0.` / `Exento requiere tasa 0.` | Usa la tarifa del catálogo. | | La tarifa del IVA corresponde a su `codigoPorcentaje` del catálogo. | `La tarifa no corresponde al codigoPorcentaje del catálogo del SRI.` / `Código de porcentaje de IVA no existe en el catálogo del SRI.` | Usa una pareja de [Catálogos: tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva). | | Los importes llevan hasta 2 decimales, y la cantidad y el precio hasta 6. | `Precisión o importe no admitido; no se redondea silenciosamente.` | Redondea en tu sistema antes de enviar. | | Solo se admiten los campos, las colecciones y los códigos de línea de la factura. | `Campo no soportado en este contrato.` | Quita el campo o usa `codigoPrincipal`. | | `moneda` tiene un valor válido. | `Este adaptador admite DOLAR o USD.` | Envía `DOLAR`. | | La factura a consumidor final llega hasta USD 50.00. | `Para una factura mayor a $50, seleccione un cliente con cedula, RUC o pasaporte...` | Pide la identificación del comprador. | | El consumidor final lleva su identificación fija. | `Identificación de consumidor final inválida.` | Envía `9999999999999`. | | La cédula tiene 10 dígitos y el RUC 13. | `Cédula tiene longitud o caracteres inválidos.` / `RUC tiene longitud o caracteres inválidos.` | Revisa `identificacionComprador`. | ## Más ejemplos Cada ejemplo es un cuerpo completo. Antes de enviarlo, cambia su `referenciaExterna` por una que no hayas usado y envía esa misma cadena como `Idempotency-Key`. Si repites las de otro envío con un cuerpo distinto, la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). ### Varias líneas con IVA 15 % y 0 % Esta factura tiene dos líneas con tarifas distintas, así que la cabecera lleva una fila por tarifa. | Línea | Cálculo | Subtotal | IVA | |---|---|---|---| | Servicio (IVA 15 %, `4`) | 2 x 25.00 | 50.00 | 50.00 x 15 / 100 = 7.50 | | Libro (IVA 0 %, `0`) | 1 x 10.00 | 10.00 | 0 | | Totales | | `totalSinImpuestos` 60.00 | 7.50 -> `importeTotal` 67.50 | ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0003", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "totalSinImpuestos": 60.00, "totalDescuento": 0, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 50.00, "valor": 7.50 }, { "codigo": "2", "codigoPorcentaje": "0", "tarifa": 0, "baseImponible": 10.00, "valor": 0 } ], "propina": 0, "importeTotal": 67.50, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 67.50 } ] }, "detalles": [ { "codigoPrincipal": "SERV-010", "descripcion": "SOPORTE TECNICO POR HORA", "cantidad": 2, "precioUnitario": 25.00, "descuento": 0, "precioTotalSinImpuesto": 50.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 50.00, "valor": 7.50 } ] }, { "codigoPrincipal": "LIB-020", "descripcion": "LIBRO TECNICO", "cantidad": 1, "precioUnitario": 10.00, "descuento": 0, "precioTotalSinImpuesto": 10.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "0", "tarifa": 0, "baseImponible": 10.00, "valor": 0 } ] } ] } ``` ### Con descuento Esta factura aplica un descuento del 10 % sobre la línea. Envía el descuento como importe en dólares: si lo manejas en porcentaje, conviértelo antes de enviarlo. | Paso | Cálculo | Resultado | |---|---|---| | Bruto | 3 x 12.50 | 37.50 | | `descuento` (10 %) | 37.50 x 10 / 100 | 3.75 | | `precioTotalSinImpuesto` | 37.50 - 3.75 | 33.75 | | IVA 15 % | 33.75 x 15 / 100 = 5.0625 | 5.06 | | `importeTotal` | 33.75 + 5.06 | 38.81 | ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0004", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "totalSinImpuestos": 33.75, "totalDescuento": 3.75, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 33.75, "valor": 5.06 } ], "propina": 0, "importeTotal": 38.81, "moneda": "DOLAR", "pagos": [ { "formaPago": "19", "total": 38.81 } ] }, "detalles": [ { "codigoPrincipal": "PROD-030", "descripcion": "CAJA DE PAPEL A4", "cantidad": 3, "precioUnitario": 12.50, "descuento": 3.75, "precioTotalSinImpuesto": 33.75, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 33.75, "valor": 5.06 } ] } ] } ``` `totalSinImpuestos` es el valor **después** del descuento, 33.75, y `totalDescuento` informa cuánto se descontó, 3.75. ### Pago a crédito con plazo Esta venta de 230.00 se paga en dos partes: 50.00 con tarjeta de crédito el mismo día y 180.00 a 30 días. | Campo | Cálculo | Valor | |---|---|---| | `precioTotalSinImpuesto` | 1 x 200.00 | 200.00 | | IVA 15 % | 200.00 x 15 / 100 | 30.00 | | `importeTotal` | 200.00 + 30.00 | 230.00 | | `pagos` | 50.00 (`19`) + 180.00 (`01`, 30 días) | 230.00 | ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0005", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "totalSinImpuestos": 200.00, "totalDescuento": 0, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 200.00, "valor": 30.00 } ], "propina": 0, "importeTotal": 230.00, "moneda": "DOLAR", "pagos": [ { "formaPago": "19", "total": 50.00 }, { "formaPago": "01", "total": 180.00, "plazo": 30, "unidadTiempo": "dias" } ] }, "detalles": [ { "codigoPrincipal": "EQ-040", "descripcion": "IMPRESORA LASER", "cantidad": 1, "precioUnitario": 200.00, "descuento": 0, "precioTotalSinImpuesto": 200.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 200.00, "valor": 30.00 } ] } ] } ``` ### Producto con ICE Esta factura tiene una línea de 100.00 gravada con ICE porcentual del 10 % e IVA 15 %. El ICE se calcula sobre el subtotal de la línea y **se suma a la base del IVA**, y en la cabecera va una fila por impuesto. | Campo | Cálculo | Valor | |---|---|---| | `precioTotalSinImpuesto` | 1 x 100.00 | 100.00 | | ICE 10 % | 100.00 x 10 / 100 | 10.00 | | Base del IVA | 100.00 + 10.00 (ICE) | 110.00 | | IVA 15 % | 110.00 x 15 / 100 | 16.50 | | `importeTotal` | 100.00 + 16.50 + 10.00 | 126.50 | El `codigoPorcentaje` 3011 y la tarifa del 10 % son ilustrativos. Usa el código y la tarifa que corresponden a tu producto según la tabla de [Tarifas de ICE](/v1/guias/catalogos#tarifas-de-ice). ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0006", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "totalSinImpuestos": 100.00, "totalDescuento": 0, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 110.00, "valor": 16.50 }, { "codigo": "3", "codigoPorcentaje": "3011", "tarifa": 10, "baseImponible": 100.00, "valor": 10.00 } ], "propina": 0, "importeTotal": 126.50, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 126.50 } ] }, "detalles": [ { "codigoPrincipal": "PRD-ICE-01", "descripcion": "PRODUCTO GRAVADO CON ICE", "cantidad": 1, "precioUnitario": 100.00, "descuento": 0, "precioTotalSinImpuesto": 100.00, "impuestos": [ { "codigo": "3", "codigoPorcentaje": "3011", "tarifa": 10, "baseImponible": 100.00, "valor": 10.00 }, { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 110.00, "valor": 16.50 } ] } ] } ``` ## Respuesta La API responde 202 Accepted con este cuerpo: ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "002-001-000000125", "referenciaExterna": "FACTURA-2026-0002", "claveAcceso": null, "fhRecibido": "2026-11-16T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido`: la factura pasó nuestras validaciones y la aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. | | `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. | | `idOperacion` | string (UUID) | Identificador de la operación. Guárdalo para el seguimiento. | | `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. | Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación, y no crea otra factura. Un 202 significa que la factura quedó **recibida**, todavía no autorizada. Sigue la operación con [`GET /v1/operaciones/{idOperacion}`](/v1/guias/consulta-operacion) o espera el [webhook](/v1/guias/webhooks). Cuando su `estado` sea `autorizado`, descarga el [RIDE](/v1/guias/consulta-ride). Si es `rechazado`, lee el `codEstado` y el detalle de `errores`, corrige la factura y reenvíala con una `Idempotency-Key` y una `referenciaExterna` nuevas, como se explica en [Reintentos y duplicados](/v1/guias/emision#reintentos-y-duplicados). ## Estados de este endpoint Esta tabla reúne las respuestas que puedes recibir al emitir una factura. | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 1001 o 1002 | 202 | La factura quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. | | 3003 (`solicitud_invalida`) | 400 | El JSON está mal formado, o la `Idempotency-Key` falta o no es válida. | Corrige la petición. | | 3002 (`comprobante_invalido`) | 422 | La factura no cumple una regla; el detalle viene en `errores`. | Corrige según [Reglas de cálculo y validaciones](#reglas-de-calculo-y-validaciones). Consume 1 documento como intento. | | 3004 (`comprobante_duplicado`) | 409 | Ya existe una factura con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo (omite `secuencial` para que se asigne el siguiente). | | 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. | | 4004 (`cupo_agotado`) | 429 | Se agotó el cupo. | Compra un paquete de documentos en el Portal del Cliente y no reintentes en bucle. Revisa [Consumo](/v1/guias/consumo). | | 3009 (`credenciales_invalidas`) | 401 | La API Key no es válida. | Revisa la API Key. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. | | 3011 (`acceso_denegado`) | 403 | El contribuyente o la factura no están habilitados, o el `ruc` no es el del contribuyente. | Revisa el contexto y el RUC enviado. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera los segundos que indica `Retry-After` y reintenta con la misma clave. | Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Seguimiento de una operación](/v1/guias/consulta-operacion): confirma si el SRI autorizó la factura. - [Webhooks](/v1/guias/webhooks): recibe la autorización o el rechazo sin consultar. - [Nota de crédito](/v1/guias/emision-04): revierte total o parcialmente una factura autorizada. - [Descarga el ejemplo de solicitud](/downloads/v1/ejemplos/example-01.json): cuerpo de factura listo para ensayar. --- # Liquidación de compra Emite una liquidación de compra cuando compras bienes o servicios a alguien que no puede entregarte una factura. Algunos proveedores no pueden emitir comprobantes, como un agricultor sin RUC o una empresa del exterior sin domicilio en Ecuador. Cuando les compras, eres tú quien emite el comprobante que respalda la compra, y ese comprobante es la liquidación de compra. Esta guía explica en qué se diferencia de la factura, te da un ejemplo mínimo listo para enviar y describe cada campo de su estructura con las reglas que valida la API. El endpoint, las cabeceras, el [secuencial](/v1/guias/glosario) automático y las reglas comunes a todos los tipos están en [Comprobantes electrónicos](/v1/guias/emision). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan > `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba). Envías la liquidación de compra a la ruta del tipo `03`. El tipo lo fija la ruta, así que el cuerpo no lleva `infoTributaria.tipoDocumento`. ``` POST /v1/contribuyentes/{identificacion}/liquidaciones-compra ``` ## Conceptos En una factura, el vendedor emite el comprobante. En una liquidación de compra es al revés: **tú, el comprador, emites el comprobante** en nombre del proveedor. Por eso `info` describe al **proveedor**, con los campos que terminan en `Proveedor`, y no a un comprador. Las líneas, los impuestos, los totales y los pagos se calculan como en la [factura](/v1/guias/emision-01), con dos diferencias: la liquidación de compra solo admite IVA, sin ICE, y no lleva propina. ## Cuándo la emites Emite una liquidación de compra en situaciones como estas: - Compras productos a una persona natural sin RUC que no puede emitir comprobantes, como un agricultor que te vende su cosecha, un pescador artesanal o un recolector de material reciclable. - Contratas un servicio ocasional a una persona sin RUC, como un trabajo puntual de reparación. - Pagas un servicio prestado por una persona o empresa del exterior sin domicilio en Ecuador. En ese caso la identificas con el tipo `06`, pasaporte, o `08`, identificación del exterior. Si tu proveedor tiene RUC y emite facturas, pídele su factura en lugar de emitir una liquidación de compra. Si además te corresponde retener impuestos sobre esta compra, emite un [comprobante de retención](/v1/guias/emision-07) con esta liquidación como documento sustento, es decir, con `codDocSustento` `03`. ## Ejemplo mínimo Este ejemplo documenta la compra de 50 kg de maíz, con IVA 0 %, y de un servicio de secado, con IVA 15 %, a un agricultor identificado con cédula, que cobra en efectivo. Guarda el JSON como `comprobante.json`, porque lo usan los ejemplos de [Envío](#envio). ```json { "origenReferencia": "MiERP", "referenciaExterna": "LIQUIDACION-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionProveedor": "05", "identificacionProveedor": "0123456789", "razonSocialProveedor": "PROVEEDOR DE PRUEBAS", "direccionProveedor": "DIRECCION DE PRUEBAS", "totalSinImpuestos": 80.00, "totalDescuento": 0, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "0", "tarifa": 0, "baseImponible": 60.00, "valor": 0 }, { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 20.00, "valor": 3.00 } ], "importeTotal": 83.00, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 83.00 } ] }, "detalles": [ { "codigoPrincipal": "MAIZ-001", "descripcion": "MAIZ EN GRANO (KG)", "cantidad": 50, "precioUnitario": 1.20, "descuento": 0, "precioTotalSinImpuesto": 60.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "0", "tarifa": 0, "baseImponible": 60.00, "valor": 0 } ] }, { "codigoPrincipal": "SERV-002", "descripcion": "SERVICIO DE SECADO DE GRANO", "cantidad": 1, "precioUnitario": 20.00, "descuento": 0, "precioTotalSinImpuesto": 20.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 20.00, "valor": 3.00 } ] } ], "infoAdicional": [ { "nombre": "Lote", "valor": "COSECHA-2026-10" } ] } ``` La tabla muestra cómo se calcula cada total del ejemplo. | Campo | Cálculo | Valor | |---|---|---| | Línea 1 (`precioTotalSinImpuesto`) | 50 x 1.20 - 0 | 60.00, IVA 0 % = 0 | | Línea 2 (`precioTotalSinImpuesto`) | 1 x 20.00 - 0 | 20.00, IVA 15 % = 3.00 | | `totalConImpuestos` | Una fila por tarifa: IVA 0 % (`0`) y IVA 15 % (`4`) | 60.00 / 0 y 20.00 / 3.00 | | `totalSinImpuestos` | 60.00 + 20.00 | 80.00 | | `importeTotal` | 80.00 + 3.00 | 83.00 | | `pagos[0].total` | Todo en efectivo (`01`) | 83.00 | La liquidación de compra no lleva `propina`. El paso a paso con descuentos y redondeo está en [Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales). ## Envío Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`, LIQUIDACION-2026-0001, así que repetir el envío no emite otra liquidación. ```bash curl -s -i -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/liquidaciones-compra" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: LIQUIDACION-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/liquidaciones-compra"); peticion.Headers.Add("Idempotency-Key", "LIQUIDACION-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/liquidaciones-compra", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "LIQUIDACION-2026-0001", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/liquidaciones-compra', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'LIQUIDACION-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: LIQUIDACION-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/liquidaciones-compra")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "LIQUIDACION-2026-0001") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; // client: EcuafactClient creado con tu API Key (ver SDK .NET) // comprobante: LiquidacionCompraRequest con la liquidacion de esta pagina EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "LIQUIDACION-2026-0001"); Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}"); ``` ```python-sdk from ecuafact import EcuafactClient # client: EcuafactClient creado con tu API Key (ver SDK Python) # comprobante: LiquidacionCompraRequest con la liquidacion de esta pagina resultado = client.emitir_en("0123456789001", comprobante, "LIQUIDACION-2026-0001") print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}") ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; // client: EcuafactClient creado con tu API Key (ver SDK Node.js) // comprobante: LiquidacionCompraRequest con la liquidacion de esta pagina const resultado = await client.emitirEn("0123456789001", comprobante, "LIQUIDACION-2026-0001"); console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'LIQUIDACION-2026-0001'); echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EmisionResultado; // client: EcuafactClient creado con tu API Key (ver SDK Java) // comprobante: LiquidacionCompraRequest con la liquidacion de esta pagina EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "LIQUIDACION-2026-0001"); System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()); ``` ```bash-cli # Resultado esperado: una fila con el estado recibido y el idOperacion de la emisión. ecuafact emitir comprobante.json --entorno sandbox ``` **Resultado esperado.** La API responde 202 con `estado` en `recibido`, el `codEstado` 1001 o 1002 y un `idOperacion`. ## Validar sin emitir Antes de emitir puedes comprobar que la liquidación está bien armada. Envía el mismo cuerpo a la ruta de validación del tipo: ``` POST /v1/contribuyentes/{identificacion}/liquidaciones-compra/validar X-Api-Key: Content-Type: application/json ``` La validación aplica las mismas reglas que la emisión, sin `Idempotency-Key`, sin consumir cupo y sin usar un número de la serie. Si la liquidación cumple todas las reglas, responde 200 con `valido` en `true` y `errores` vacío; si no, responde el mismo error que daría la emisión. Los detalles están en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). ## Estructura del comprobante El cuerpo de la liquidación de compra se organiza en bloques, y cada tabla describe uno. ### Raíz | Clave | Tipo | Obligatorio | Regla | |---|---|---|---| | `origenReferencia` | string | Sí | Nombre de tu sistema, de 1 a 64 caracteres entre letras y dígitos ASCII y `-` `_` `.` `:` `/`. | | `referenciaExterna` | string | Sí | Tu número interno de la compra, de 1 a 128 caracteres con el mismo alfabeto. | | `infoTributaria` | object | Sí | Identidad del comprobante. Sus campos están en la tabla siguiente. | | `info` | object | Sí | Cabecera de la liquidación, que se describe más abajo. | | `detalles` | array | Sí | De 1 a 1000 líneas. | | `infoAdicional` | array | No | Hasta 15 objetos `{ "nombre", "valor" }`, cada uno de 1 a 300 caracteres. | ### `infoTributaria` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `ruc` | string | Sí | Tu RUC completo, el del comprador que emite, de 13 dígitos; en pruebas, `0123456789001`. | | `estab` | string | Sí | Establecimiento, de hasta 3 dígitos. Se completa con ceros. | | `ptoEmi` | string | Sí | Punto de emisión, de hasta 3 dígitos. Se completa con ceros. | | `secuencial` | string | No | Hasta 9 dígitos. Omítelo y te asignamos el siguiente de la serie de liquidaciones, como se explica en [Secuencial automático](/v1/guias/emision#secuencial-automatico). | ### `info` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `fechaEmision` | string | Sí | `dd/MM/yyyy`. Envía la fecha de hoy, porque el comprobante autorizado lleva la fecha del día en que se procesa. | | `dirEstablecimiento` | string | No | Dirección de tu establecimiento, hasta 300 caracteres. | | `tipoIdentificacionProveedor` | string | Sí | `05` cédula, `06` pasaporte, `08` identificación del exterior o `04` RUC. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). `07`, consumidor final, no se admite. | | `identificacionProveedor` | string | Sí | Con `04`, 13 dígitos. Con `05`, 10 dígitos. Con `06` y `08`, hasta 20 caracteres. | | `razonSocialProveedor` | string | Sí | Nombre del proveedor, hasta 300 caracteres. | | `direccionProveedor` | string | No | Hasta 300 caracteres. | | `telefono` | string | No | Teléfono del proveedor, hasta 40 caracteres. | | `correo` | string | No | Correo del proveedor al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se toma un campo de `infoAdicional` llamado `email` o `correo`. | | `totalSinImpuestos` | number | Sí | Suma de `detalles[].precioTotalSinImpuesto`. | | `totalDescuento` | number | Sí | Suma de `detalles[].descuento`. Envía `0` si no hay. | | `totalConImpuestos` | array | Sí | Una o dos filas, una por cada pareja `codigo` + `codigoPorcentaje` de las líneas, con la suma de sus bases y valores. `tarifa` es opcional y, si la envías, debe ser igual a la de las líneas. | | `importeTotal` | number | Sí | `totalSinImpuestos` + IVA. | | `moneda` | string | Sí | `DOLAR` o `USD`. | | `pagos` | array | Sí | De 1 a 20 formas de pago, cuya suma es igual a `importeTotal`. Llevan los mismos campos que en la factura (`formaPago`, `total`, `plazo` y `unidadTiempo`), y sus códigos están en [Catálogos: formas de pago](/v1/guias/catalogos#formas-de-pago). | No envíes `propina`, ni siquiera con `0`, ni `guiaRemision`, `placa` o los campos `...Comprador`. Si los envías, la API responde 422 con `Campo no soportado en este contrato.` ### `detalles[]` e impuestos Las líneas y sus impuestos son iguales a los de la factura. | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codigoPrincipal` | string | Sí | Código del bien o servicio, hasta 25 caracteres. | | `codigoAuxiliar` | string | No | Hasta 25 caracteres. | | `descripcion` | string | Sí | Hasta 300 caracteres. | | `cantidad` | number | Sí | Mayor que 0, hasta 6 decimales. | | `precioUnitario` | number | Sí | Mayor o igual a 0, hasta 6 decimales, sin IVA. | | `descuento` | number | Sí | Importe en dólares, con 2 decimales como máximo. | | `precioTotalSinImpuesto` | number | Sí | `cantidad x precioUnitario - descuento`, redondeado a 2 decimales. | | `impuestos` | array | Sí | Un solo IVA, con `codigo` `"2"`. El ICE no se admite en la liquidación de compra. Lleva `codigoPorcentaje`, `tarifa`, `baseImponible` y `valor`, y sus reglas completas están en [Factura](/v1/guias/emision-01). | | `detallesAdicionales` | array | No | Hasta 3 objetos `{ "nombre", "valor" }`. | No uses `codigoInterno` ni `codigoAdicional`, porque la API responde 422 con `Campo no soportado en este contrato.` Tampoco envíes `unidadMedida` ni `precioSinSubsidio`, porque la API no los procesa y los rechaza como campos desconocidos. ## Reglas de cálculo y validaciones Las fórmulas de líneas, impuestos, totales y pagos son las de [Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales). Si una regla no se cumple, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`). Estos son los errores típicos de la liquidación de compra: | Error típico | Mensaje (en `errores`) | Qué hacer | |---|---|---| | Enviar `propina`, aunque sea `0`. | `$.info.propina: Campo no soportado en este contrato.` | Quita `propina`. | | Usar los campos de la factura, como `tipoIdentificacionComprador`. | `$.info.tipoIdentificacionComprador: Campo no soportado en este contrato.` | Usa `tipoIdentificacionProveedor`, `identificacionProveedor` y `razonSocialProveedor`. | | Identificar al proveedor como consumidor final (`07`). | `...requiere un contribuyente identificado.` | Identifica al proveedor con cédula, pasaporte o identificación del exterior. | | Enviar una cédula que no tiene 10 dígitos o un RUC que no tiene 13. | `Cédula tiene longitud o caracteres inválidos.` / `RUC tiene longitud o caracteres inválidos.` | Revisa la identificación del proveedor. | | Omitir `pagos`. | `$.info.pagos: Lista vacia, invalida o demasiado extensa.` | Informa cómo pagas al proveedor. | | Usar `codigoInterno` en las líneas. | `Campo no soportado en este contrato.` | Usa `codigoPrincipal`. | | Enviar un ICE (`codigo` `"3"`) en una línea. | `La liquidación de compra solo admite IVA.` | Deja solo el IVA en cada línea. | | Enviar totales que no cuadran. | `Totales no coinciden con detalles.` / `total no coincide con subtotal + IVA + ICE + propina.` / `Pagos no coinciden con total.` | Recalcula con las fórmulas. | | Calcular mal una línea. | `Subtotal del detalle no coincide con cantidad × precio − descuento.` / `Valor de impuesto no coincide con base y tasa.` | Recalcula la línea como en la [factura](/v1/guias/emision-01#reglas-de-calculo-y-validaciones). | | Omitir `unidadTiempo` cuando hay plazo. | `Obligatoria cuando hay plazo.` | Agrega `"unidadTiempo": "dias"`. | ## Respuesta La API responde 202 Accepted con este cuerpo: ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "03", "numeroDocumento": "002-001-000000001", "referenciaExterna": "LIQUIDACION-2026-0001", "claveAcceso": null, "fhRecibido": "2026-11-16T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. | | `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. | | `idOperacion` | string (UUID) | Identificador de la operación. Guárdalo para el seguimiento. | | `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. | Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error. Un 202 significa que la liquidación quedó **recibida**, todavía no autorizada. Sigue la operación con [`GET /v1/operaciones/{idOperacion}`](/v1/guias/consulta-operacion) o espera el [webhook](/v1/guias/webhooks). Cuando su `estado` sea `autorizado`, descarga el [RIDE](/v1/guias/consulta-ride) y entrégalo al proveedor. ## Estados de este endpoint Esta tabla reúne las respuestas que puedes recibir al emitir una liquidación de compra. | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 1001 o 1002 | 202 | La liquidación quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. No reenvíes con otros datos. | | 3003 (`solicitud_invalida`) | 400 | El JSON está mal formado, o la `Idempotency-Key` falta o no es válida. | Corrige la petición. | | 3002 (`comprobante_invalido`) | 422 | La liquidación no cumple una regla; el detalle viene en `errores`. | Corrige según la tabla de errores típicos. Consume 1 documento como intento. | | 3004 (`comprobante_duplicado`) | 409 | Ya existe una liquidación con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo (omite `secuencial` para que se asigne el siguiente). | | 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. | | 4004 (`cupo_agotado`) | 429 | Se agotó el cupo. | Compra un paquete de documentos en el Portal del Cliente y no reintentes en bucle. Revisa [Consumo](/v1/guias/consumo). | | 3009 (`credenciales_invalidas`) | 401 | La API Key no es válida. | Revisa la API Key. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. | | 3011 (`acceso_denegado`) | 403 | La liquidación de compra no está habilitada para tu integración, o el `ruc` no es el del contribuyente. | Revisa `tiposComprobante` en el contexto y el RUC enviado. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera los segundos que indica `Retry-After` y reintenta con la misma clave. | Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Comprobante de retención](/v1/guias/emision-07): retiene impuestos sobre esta compra usando la liquidación como sustento. - [Seguimiento de una operación](/v1/guias/consulta-operacion): confirma si el SRI autorizó la liquidación. - [Webhooks](/v1/guias/webhooks): recibe la autorización o el rechazo sin consultar. - [Descarga el ejemplo de solicitud](/downloads/v1/ejemplos/example-03.json): cuerpo de liquidación listo para ensayar. --- # Nota de crédito Emite una nota de crédito para devolver dinero, aplicar un descuento posterior o anular total o parcialmente una factura autorizada. Un comprobante autorizado no se puede editar ni borrar. Cuando necesitas devolver dinero, conceder un descuento después de facturar o anular una venta, emites una nota de crédito que apunta a la factura original y dice cuánto se acredita al comprador. Esta guía explica cómo identificar la factura que modificas, te da un ejemplo mínimo de devolución parcial listo para enviar y describe cada campo con las reglas que valida la API. El endpoint, las cabeceras, el [secuencial](/v1/guias/glosario) automático y las reglas comunes a todos los tipos están en [Comprobantes electrónicos](/v1/guias/emision). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan > `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba). La ruta de emisión fija el tipo `04`. Si quieres comprobar el cuerpo antes de emitir, usa la ruta de validación, que aplica las mismas reglas y no consume cupo. ``` POST /v1/contribuyentes/{identificacion}/notas-credito POST /v1/contribuyentes/{identificacion}/notas-credito/validar ``` No envíes `infoTributaria.tipoDocumento`. La validación se explica en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). ## Conceptos La factura a la que **apunta** la nota de crédito es el documento modificado o [sustento](/v1/guias/glosario). Además del valor que se acredita al comprador, la nota indica por qué se acredita. - Los valores de la nota son **positivos**: representan lo que devuelves o descuentas. No envíes importes negativos, porque la API responde 422. - El comprador es el mismo de la factura original. - La nota lleva sus propias líneas (`detalles`) con lo que se acredita, sus impuestos y sus totales. No lleva pagos. ## Cuándo la emites Emite una nota de crédito en situaciones como estas: - **Devolución parcial**: el cliente devuelve uno de los productos que compró. La nota lleva solo la línea devuelta. - **Devolución total o anulación de la venta**: se revierte toda la factura. La nota lleva todas las líneas y su valor es igual al total de la factura. - **Descuento posterior a la venta**: un descuento por pronto pago o una bonificación por volumen que concedes después de facturar. La nota lleva una línea con el valor del descuento y su IVA. - **Corrección de un precio cobrado de más**: la nota acredita la diferencia. Para cobrar un valor **adicional** sobre una factura, como intereses o recargos, usa una [nota de débito](/v1/guias/emision-05), no una nota de crédito. ## Referencia al documento modificado Con cuatro campos de `info` identificas la factura que modificas. Cópialos de tu registro de la factura original, porque la API **no los busca ni los completa** por ti. | Campo | De dónde sale | Formato | Ejemplo | |---|---|---|---| | `codDocModificado` | Tipo del comprobante original. Casi siempre una factura. | Hasta 2 dígitos, completados con ceros a la izquierda. | `"01"` | | `numDocModificado` | Número de la factura: `estab-ptoEmi-secuencial`. Es lo que se imprime en el RIDE y lo que devuelve `numeroDocumento` en el seguimiento. | `ddd-ddd-ddddddddd` (3, 3 y 9 dígitos separados por guiones). | `"002-001-000000123"` | | `fechaEmisionDocSustento` | `fechaEmision` de la factura original. | `dd/MM/yyyy`. | `"01/10/2026"` | | `totalDocumentoSustento` | `importeTotal` de la factura original. Opcional, pero recomendado. | Número con 2 decimales. | `115.00` | El campo `numDocModificado` admite algunas variantes de formato: - Si un segmento tiene menos dígitos, la API lo completa con ceros: `"2-1-123"` se toma como `"002-001-000000123"`. Te recomendamos enviar el formato completo para evitar dudas. - También se acepta sin guiones si tiene entre 10 y 15 dígitos, como `"002001000000123"`. - Si envías solo el secuencial, como `"123"` o `"000000123"`, la API lo rechaza, porque no supone el establecimiento ni el punto de emisión. Si envías `totalDocumentoSustento`, la API comprueba que `valorModificacion` no lo supere. Si emites varias notas de crédito para una misma factura, controla en tu sistema que su suma no supere el total de la factura, porque la API no lleva el saldo acumulado de las notas anteriores. ## Ejemplo mínimo Este ejemplo es una devolución parcial. De la factura 002-001-000000123 del 01/10/2026, con un total de 115.00, el cliente devuelve un servicio de 20.00 con IVA 15 %. Guarda el JSON como `comprobante.json`, porque lo usan los ejemplos de [Envío](#envio). ```json { "origenReferencia": "MiERP", "referenciaExterna": "NOTACREDITO-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "codDocModificado": "01", "numDocModificado": "002-001-000000123", "fechaEmisionDocSustento": "01/10/2026", "totalDocumentoSustento": 115.00, "totalSinImpuestos": 20.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 20.00, "valor": 3.00 } ], "valorModificacion": 23.00, "moneda": "DOLAR", "motivo": "DEVOLUCION PARCIAL DEL SERVICIO" }, "detalles": [ { "codigoInterno": "SERV-001", "descripcion": "DEVOLUCION SERVICIO DE MANTENIMIENTO", "cantidad": 1, "precioUnitario": 20.00, "descuento": 0, "precioTotalSinImpuesto": 20.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 20.00, "valor": 3.00 } ] } ] } ``` La tabla muestra cómo se calcula cada total del ejemplo. | Campo | Cálculo | Valor | |---|---|---| | `detalles[0].precioTotalSinImpuesto` | 1 x 20.00 - 0 | 20.00 | | `detalles[0].impuestos[0].valor` | 20.00 x 15 / 100 | 3.00 | | `totalConImpuestos[0]` | Suma de las líneas con IVA 15 % (`4`) | base 20.00, valor 3.00 | | `totalSinImpuestos` | Suma de `precioTotalSinImpuesto` | 20.00 | | `valorModificacion` | `totalSinImpuestos` + IVA + ICE = 20.00 + 3.00 | 23.00 | | Control de saldo | 23.00 no supera `totalDocumentoSustento` (115.00) | Correcto | `valorModificacion` ocupa en la nota de crédito el lugar de `importeTotal`: es el total que se acredita al comprador, con impuestos. Las líneas y los impuestos se calculan igual que en [Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales). ## Envío Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`, NOTACREDITO-2026-0001, así que repetir el envío no emite otra nota. ```bash curl -s -i -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: NOTACREDITO-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/notas-credito"); peticion.Headers.Add("Idempotency-Key", "NOTACREDITO-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "NOTACREDITO-2026-0001", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'NOTACREDITO-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: NOTACREDITO-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "NOTACREDITO-2026-0001") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; // client: EcuafactClient creado con tu API Key (ver SDK .NET) // comprobante: NotaCreditoRequest con la nota de credito de esta pagina EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "NOTACREDITO-2026-0001"); Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}"); ``` ```python-sdk from ecuafact import EcuafactClient # client: EcuafactClient creado con tu API Key (ver SDK Python) # comprobante: NotaCreditoRequest con la nota de credito de esta pagina resultado = client.emitir_en("0123456789001", comprobante, "NOTACREDITO-2026-0001") print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}") ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; // client: EcuafactClient creado con tu API Key (ver SDK Node.js) // comprobante: NotaCreditoRequest con la nota de credito de esta pagina const resultado = await client.emitirEn("0123456789001", comprobante, "NOTACREDITO-2026-0001"); console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'NOTACREDITO-2026-0001'); echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EmisionResultado; // client: EcuafactClient creado con tu API Key (ver SDK Java) // comprobante: NotaCreditoRequest con la nota de credito de esta pagina EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "NOTACREDITO-2026-0001"); System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()); ``` ```bash-cli # Resultado esperado: una fila con el estado recibido y el idOperacion de la emisión. ecuafact emitir comprobante.json --entorno sandbox ``` **Resultado esperado.** La API responde 202 con `estado` en `recibido`, el `codEstado` 1001 o 1002 y un `idOperacion`. ## Estructura del comprobante El cuerpo de la nota de crédito se organiza en bloques, y cada tabla describe uno. ### Raíz | Clave | Tipo | Obligatorio | Regla | |---|---|---|---| | `origenReferencia` | string | Sí | Nombre de tu sistema, de 1 a 64 caracteres entre letras y dígitos ASCII y `-` `_` `.` `:` `/`. | | `referenciaExterna` | string | Sí | Tu número interno de la nota, de 1 a 128 caracteres con el mismo alfabeto. | | `infoTributaria` | object | Sí | Identidad del comprobante. Sus campos están en la tabla siguiente. | | `info` | object | Sí | Cabecera de la nota, que se describe más abajo. | | `detalles` | array | Sí | De 1 a 1000 líneas con lo que se acredita. | | `infoAdicional` | array | No | Hasta 15 objetos `{ "nombre", "valor" }`, cada uno de 1 a 300 caracteres. | ### `infoTributaria` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `ruc` | string | Sí | RUC completo del emisor, de 13 dígitos; en pruebas, `0123456789001`. | | `estab` | string | Sí | Establecimiento de la nota, de hasta 3 dígitos. Se completa con ceros. Puede ser distinto del de la factura. | | `ptoEmi` | string | Sí | Punto de emisión de la nota, de hasta 3 dígitos. Se completa con ceros. | | `secuencial` | string | No | Hasta 9 dígitos. Omítelo y te asignamos el siguiente de la serie de notas de crédito, que es independiente de la serie de facturas. | ### `info` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `fechaEmision` | string | Sí | Fecha de la nota, `dd/MM/yyyy`. Envía la fecha de hoy, porque el comprobante autorizado lleva la fecha del día en que se procesa. | | `dirEstablecimiento` | string | No | Hasta 300 caracteres. | | `tipoIdentificacionComprador` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte u `08` identificación del exterior. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). `07`, consumidor final, no se admite. | | `identificacionComprador` | string | Sí | La del comprador de la factura original. Con `04`, 13 dígitos; con `05`, 10 dígitos; con `06` y `08`, hasta 20 caracteres. | | `razonSocialComprador` | string | Sí | Hasta 300 caracteres. | | `direccionComprador` | string | No | Hasta 300 caracteres. | | `telefono` | string | No | Hasta 40 caracteres. | | `correo` | string | No | Correo del comprador al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se toma un campo de `infoAdicional` llamado `email` o `correo`. | | `codDocModificado` | string | Sí | Tipo del documento modificado, normalmente `"01"`. Se explica en [Referencia al documento modificado](#referencia-al-documento-modificado). | | `numDocModificado` | string | Sí | `ddd-ddd-ddddddddd`. | | `fechaEmisionDocSustento` | string | Sí | Fecha de la factura original, `dd/MM/yyyy`. | | `totalDocumentoSustento` | number | No | `importeTotal` de la factura original. Si llega, `valorModificacion` no puede superarlo. | | `totalSinImpuestos` | number | Sí | Suma de `detalles[].precioTotalSinImpuesto`. | | `totalConImpuestos` | array | Sí | Una o dos filas, una por cada pareja `codigo` + `codigoPorcentaje` de las líneas, con `baseImponible` y `valor` sumados. `tarifa` es opcional. | | `valorModificacion` | number | Sí | `totalSinImpuestos` + IVA + ICE. Es el total acreditado. | | `moneda` | string | Sí | `DOLAR` o `USD`. | | `motivo` | string | Sí | Razón de la nota, como `DEVOLUCION` o `DESCUENTO POR PRONTO PAGO`, de hasta 300 caracteres. Los saltos de línea se convierten en espacios. | No envíes `totalDescuento`, `propina`, `importeTotal` ni `pagos`. Si los envías, aunque lleven `0`, la API responde 422 con `Campo no soportado en este contrato.` ### `detalles[]` En la nota de crédito, las líneas usan `codigoInterno` y `codigoAdicional` en lugar de `codigoPrincipal` y `codigoAuxiliar`. | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codigoInterno` | string | Sí | Código del bien o servicio, hasta 25 caracteres. Usa el mismo de la factura. | | `codigoAdicional` | string | No | Hasta 25 caracteres. | | `descripcion` | string | Sí | Hasta 300 caracteres. | | `cantidad` | number | Sí | Cantidad acreditada, mayor que 0, hasta 6 decimales. | | `precioUnitario` | number | Sí | Mayor o igual a 0, hasta 6 decimales, sin IVA. | | `descuento` | number | Sí | Importe en dólares, con 2 decimales como máximo. Envía `0` si no hay. | | `precioTotalSinImpuesto` | number | Sí | `cantidad x precioUnitario - descuento`, redondeado a 2 decimales. | | `impuestos` | array | Sí | Un IVA, con `"2"`, y como máximo un ICE, con `"3"`, cada uno con `codigoPorcentaje`, `tarifa`, `baseImponible` y `valor`. Usa la misma tarifa que tuvo la línea en la factura; las reglas están en [Factura](/v1/guias/emision-01). | | `detallesAdicionales` | array | No | Hasta 3 objetos `{ "nombre", "valor" }`. | ## Reglas de cálculo y validaciones Las líneas e impuestos siguen [Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales). Si una regla no se cumple, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`). Estos son los errores típicos de la nota de crédito: | Error típico | Mensaje (en `errores`) | Qué hacer | |---|---|---| | Enviar en `numDocModificado` solo el secuencial. | `$.info.numDocModificado: Indique establecimiento y punto de emision; no se infieren.` | Envía `002-001-000000123`. | | Enviar `numDocModificado` con otra cantidad de segmentos, como `002-001`. | `$.info.numDocModificado: Use estab-pto-secuencial.` | Usa tres segmentos separados por guiones. | | Enviar `numDocModificado` con letras o con segmentos demasiado largos. | `Solo se admiten digitos.` / `Longitud excedida.` | Usa como máximo 3, 3 y 9 dígitos. | | Enviar la fecha del sustento en otro formato. | `$.info.fechaEmisionDocSustento: Use dd/MM/yyyy, como el SRI.` | Usa `01/10/2026`. | | La nota supera el total de la factura. | `El valor de la nota de credito no puede superar el total del documento que acredita.` | Revisa `valorModificacion` y `totalDocumentoSustento`. | | Calcular mal `valorModificacion`. | `total no coincide con subtotal + IVA + ICE + propina.` | Calcula `valorModificacion` como `totalSinImpuestos` + IVA + ICE. | | Enviar `pagos`, `totalDescuento`, `propina` o `importeTotal`. | `$.info.pagos: Campo no soportado en este contrato.` | Quita esos campos. | | Usar `codigoPrincipal` en las líneas. | `$.detalles[0].codigoPrincipal: Campo no soportado en este contrato.` | Cambia a `codigoInterno`. | | Identificar al comprador como consumidor final (`07`). | `...requiere un contribuyente identificado.` | Identifica al comprador como en la factura original. | | Enviar importes negativos. | `Numero fuera de rango.` | Envía valores positivos. | | Falta `motivo`. | `$.info.motivo: Campo obligatorio.` | Explica la razón de la nota. | | Calcular mal una línea. | `Subtotal del detalle no coincide con cantidad × precio − descuento.` / `Valor de impuesto no coincide con base y tasa.` | Recalcula la línea como en la [factura](/v1/guias/emision-01#reglas-de-calculo-y-validaciones). | | Enviar un `totalConImpuestos` que no cuadra con las líneas. | `Base o valor de impuestos no coincide con detalles.` | Suma bases y valores por `codigo` + `codigoPorcentaje`. | | `totalSinImpuestos` o el IVA no cuadran con las líneas. | `Totales no coinciden con detalles.` | Suma de nuevo las líneas. | Antes de emitir, te recomendamos comprobar en tu sistema que la factura modificada exista y esté autorizada, que el comprador coincida con el de la factura, que la fecha de la nota sea posterior a la de la factura y que la suma de varias notas no supere la factura. La API **no** hace esas comprobaciones; algunas puede hacerlas el SRI. ## Más ejemplos Cada ejemplo es un cuerpo completo. Antes de enviarlo, cambia su `referenciaExterna` por una que no hayas usado y envía esa misma cadena como `Idempotency-Key`. ### Devolución total de la factura Esta nota anula toda la factura 002-001-000000123, de 100.00 más 15.00 de IVA, es decir, 115.00. Su `valorModificacion` es igual a `totalDocumentoSustento`, lo que está permitido. ```json { "origenReferencia": "MiERP", "referenciaExterna": "NOTACREDITO-2026-0002", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "codDocModificado": "01", "numDocModificado": "002-001-000000123", "fechaEmisionDocSustento": "01/10/2026", "totalDocumentoSustento": 115.00, "totalSinImpuestos": 100.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 100.00, "valor": 15.00 } ], "valorModificacion": 115.00, "moneda": "DOLAR", "motivo": "ANULACION DE LA VENTA" }, "detalles": [ { "codigoInterno": "SERV-001", "descripcion": "SERVICIO DE MANTENIMIENTO", "cantidad": 1, "precioUnitario": 100.00, "descuento": 0, "precioTotalSinImpuesto": 100.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 100.00, "valor": 15.00 } ] } ] } ``` ### Descuento posterior por pronto pago El cliente pagó antes de tiempo y le concedes 5.00 de descuento sobre la misma factura. La nota lleva una línea de 5.00 con IVA 15 %, cuyo IVA es 5.00 x 15 / 100 = 0.75, así que `valorModificacion` es 5.00 + 0.75 = 5.75. ```json { "origenReferencia": "MiERP", "referenciaExterna": "NOTACREDITO-2026-0003", "infoTributaria": { "ruc": "0123456789001", "estab": "002", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS", "codDocModificado": "01", "numDocModificado": "002-001-000000123", "fechaEmisionDocSustento": "01/10/2026", "totalDocumentoSustento": 115.00, "totalSinImpuestos": 5.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 5.00, "valor": 0.75 } ], "valorModificacion": 5.75, "moneda": "DOLAR", "motivo": "DESCUENTO POR PRONTO PAGO" }, "detalles": [ { "codigoInterno": "DESC-PP", "descripcion": "DESCUENTO POR PRONTO PAGO", "cantidad": 1, "precioUnitario": 5.00, "descuento": 0, "precioTotalSinImpuesto": 5.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 5.00, "valor": 0.75 } ] } ] } ``` ## Respuesta La API responde 202 Accepted con este cuerpo: ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "04", "numeroDocumento": "002-001-000000001", "referenciaExterna": "NOTACREDITO-2026-0001", "claveAcceso": null, "fhRecibido": "2026-11-16T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. | | `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. | | `idOperacion` | string (UUID) | Identificador de la operación. Guárdalo para el seguimiento. | | `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. | Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error. Un 202 significa que la nota quedó **recibida**, todavía no autorizada. Sigue la operación con [`GET /v1/operaciones/{idOperacion}`](/v1/guias/consulta-operacion) o espera el [webhook](/v1/guias/webhooks). Registra en tu sistema el crédito al cliente solo cuando su `estado` sea `autorizado`. ## Estados de este endpoint Esta tabla reúne las respuestas que puedes recibir al emitir una nota de crédito. | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 1001 o 1002 | 202 | La nota de crédito quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. No reenvíes con otros datos. | | 3003 (`solicitud_invalida`) | 400 | El JSON está mal formado, o la `Idempotency-Key` falta o no es válida. | Corrige la petición. | | 3002 (`comprobante_invalido`) | 422 | La nota no cumple una regla; el detalle viene en `errores`. | Corrige según la tabla de errores típicos. Consume 1 documento como intento. | | 3004 (`comprobante_duplicado`) | 409 | Ya existe una nota de crédito con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo (omite `secuencial` para que se asigne el siguiente). | | 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. | | 4004 (`cupo_agotado`) | 429 | Se agotó el cupo. | Compra un paquete de documentos en el Portal del Cliente y no reintentes en bucle. Revisa [Consumo](/v1/guias/consumo). | | 3009 (`credenciales_invalidas`) | 401 | La API Key no es válida. | Revisa la API Key. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. | | 3011 (`acceso_denegado`) | 403 | La nota de crédito no está habilitada para tu integración, o el `ruc` no es el del contribuyente. | Revisa `tiposComprobante` en el contexto y el RUC enviado. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera los segundos que indica `Retry-After` y reintenta con la misma clave. | Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Seguimiento de una operación](/v1/guias/consulta-operacion): confirma si el SRI autorizó la nota. - [Factura](/v1/guias/emision-01): repasa los campos y cálculos de la factura que modificas. - [Nota de débito](/v1/guias/emision-05): cobra un valor adicional sobre una factura. - [Descarga el ejemplo de solicitud](/downloads/v1/ejemplos/example-04.json): cuerpo de nota de crédito listo para ensayar. --- # Nota de débito Emite una nota de débito para cobrar intereses, recargos u otros ajustes al alza sobre una factura que ya emitiste. La nota de débito aumenta lo que el comprador te debe por un comprobante ya emitido, sin anularlo. Esta guía te da un ejemplo mínimo listo para enviar, explica cómo se calculan sus totales y describe cada campo con las reglas que valida la API. El endpoint, las cabeceras y las reglas comunes a todos los tipos están en [Comprobantes electrónicos](/v1/guias/emision). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba). Envías la nota de débito a su endpoint de emisión. El tipo lo fija la ruta, así que el cuerpo no lleva `infoTributaria.tipoDocumento`. ``` POST /v1/contribuyentes/{identificacion}/notas-debito Cabeceras: X-Api-Key, Idempotency-Key, Content-Type: application/json POST /v1/contribuyentes/{identificacion}/notas-debito/validar Cabeceras: X-Api-Key, Content-Type: application/json ``` La ruta `/validar` comprueba el cuerpo sin emitirlo, sin `Idempotency-Key` y sin consumir cupo. Responde 200 con `valido` en `true` y `errores` vacío, o el mismo error que daría la emisión, como se explica en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). ## Conceptos - **Documento modificado**: el comprobante que la nota de débito incrementa, normalmente una factura. Lo identificas con su tipo en `codDocModificado`, su número en `numDocModificado` y su fecha en `fechaEmisionDocSustento`. Cópialos de tu registro, porque usamos los datos que envías sin buscarlos ni corregirlos. - **Motivos**: en lugar de líneas de productos, la nota de débito lleva en `motivos` una lista de razones, cada una con su valor **sin impuestos**. - **Un solo IVA**: todos los motivos comparten la tarifa de IVA declarada en `info.impuestos`. Con esa tarifa calculas el IVA de cada motivo y envías su suma. Los demás términos, como [RUC](/v1/guias/glosario), [secuencial](/v1/guias/glosario), [clave de acceso](/v1/guias/glosario) o [RIDE](/v1/guias/glosario), están explicados en el [Glosario](/v1/guias/glosario). ## Cuándo la emites Estos son los casos habituales en los que emites una nota de débito: - Intereses por mora: el cliente pagó una factura después del vencimiento. - Gastos de cobranza, de envío o bancarios que cobras después de la venta. - Un ajuste de precio al alza que no incluiste en la factura original. Si en lugar de aumentar necesitas **disminuir** el valor, por una devolución o un descuento posterior, emite una [Nota de crédito](/v1/guias/emision-04). ## Antes de empezar - [ ] Una API Key de pruebas en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea tu sandbox](/v1/guias/sandbox). - [ ] En el ambiente de pruebas puedes llamar desde cualquier IP. En producción, la IP desde la que llamas debe estar registrada para tu API Key, como se explica en [Autenticación](/v1/guias/autenticacion). - [ ] El valor `identificacion` de tu contribuyente, que obtienes con [`GET /v1/contexto`](/v1/guias/consulta-contexto). En los ejemplos es `0123456789001`. - [ ] El tipo `05` habilitado para ese contribuyente, es decir, que aparezca en `tiposComprobante` del contexto. - [ ] Los datos del documento modificado: tipo, número `ddd-ddd-ddddddddd` y fecha de emisión. ## Ejemplo mínimo Este ejemplo es una nota de débito por intereses y gastos de cobranza sobre la factura 001-001-000000123, con IVA 15 %. Guarda el JSON como `comprobante.json`, porque lo usan los ejemplos de [Envío](#envio). ```json { "origenReferencia": "MiERP", "referenciaExterna": "ND-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001", "secuencial": "000000000" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "05", "identificacionComprador": "0123456789", "razonSocialComprador": "CLIENTE DE PRUEBAS", "codDocModificado": "01", "numDocModificado": "001-001-000000123", "fechaEmisionDocSustento": "01/10/2026", "totalSinImpuestos": 30.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 30.00, "valor": 4.50 } ], "valorTotal": 34.50, "pagos": [ { "formaPago": "20", "total": 34.50, "plazo": 15, "unidadTiempo": "dias" } ] }, "motivos": [ { "razon": "INTERESES POR MORA", "valor": 20.00 }, { "razon": "GASTOS DE COBRANZA", "valor": 10.00 } ], "infoAdicional": [ { "nombre": "email", "valor": "cliente@example.com" } ] } ``` Con `"secuencial": "000000000"` te asignamos el siguiente número de la serie 001-001 de notas de débito, y omitir el campo tiene el mismo efecto. ### Cómo se calculan los totales | Paso | Cálculo | Resultado | Campo | |---|---|---|---| | 1. Suma los valores de los motivos (sin IVA) | 20.00 + 10.00 | 30.00 | `info.totalSinImpuestos` y `info.impuestos[0].baseImponible` | | 2. IVA de cada motivo, redondeado a 2 decimales | 20.00 x 15 / 100 = 3.00; 10.00 x 15 / 100 = 1.50 | 3.00 y 1.50 | No se envía; solo lo calculas para sumarlo en el paso 3. | | 3. Suma los IVA de los motivos | 3.00 + 1.50 | 4.50 | `info.impuestos[0].valor` | | 4. Total de la nota | 30.00 + 4.50 | 34.50 | `info.valorTotal` | | 5. Reparte el total en formas de pago | 34.50 | 34.50 | suma de `info.pagos[].total` | El IVA se redondea **por motivo**, a 2 decimales y con la mitad hacia arriba, y después se suma. Si lo calculas sobre el total y no por motivo, puede diferir en un centavo, y la API responde 422. ## Envío Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`, ND-2026-0001. ```bash curl -s -i -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-debito" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: ND-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/notas-debito"); peticion.Headers.Add("Idempotency-Key", "ND-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-debito", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "ND-2026-0001", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-debito', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'ND-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: ND-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-debito")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "ND-2026-0001") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using System.Text.Json; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); NotaDebitoRequest comprobante = JsonSerializer.Deserialize( await File.ReadAllTextAsync("comprobante.json"))!; EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "ND-2026-0001"); Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}"); ``` ```python-sdk import json import os from ecuafact import NotaDebitoRequest, EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) with open("comprobante.json", encoding="utf-8") as archivo: comprobante = NotaDebitoRequest.model_validate(json.load(archivo)) resultado = client.emitir_en("0123456789001", comprobante, "ND-2026-0001") print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}") ``` ```javascript-sdk // Node.js 18 o superior. Guarda como emitir-sdk.mjs y ejecuta: node emitir-sdk.mjs import { readFile } from 'node:fs/promises'; import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const comprobante = JSON.parse(await readFile('comprobante.json', 'utf8')); const resultado = await client.emitirNotaDebitoEn('0123456789001', comprobante, 'ND-2026-0001'); console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'ND-2026-0001'); echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.contracts.NotaDebitoRequest; import com.fasterxml.jackson.databind.ObjectMapper; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); NotaDebitoRequest comprobante = new ObjectMapper() .readValue(Files.readString(Path.of("comprobante.json")), NotaDebitoRequest.class); EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "ND-2026-0001"); System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()); ``` ```bash-cli # Resultado esperado: una fila con el estado recibido y el idOperacion de la nota. ecuafact emitir comprobante.json --entorno sandbox ``` Si repites exactamente la misma solicitud, con la misma `Idempotency-Key` y el mismo cuerpo, por ejemplo tras un timeout, la API no crea otra nota. Responde 202 con el mismo `idOperacion` y el estado actual de la operación. ## Estructura del comprobante El cuerpo de la nota de débito se organiza en bloques, y cada tabla describe uno. ### Raíz | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `origenReferencia` | string | Sí | Nombre de tu sistema de origen, de hasta 64 caracteres entre letras y dígitos ASCII y `- _ . : /`. | | `referenciaExterna` | string | Sí | Identificador estable del documento en tu sistema, de hasta 128 caracteres con el mismo alfabeto. Repítelo igual en cada reintento. | | `infoTributaria` | object | Sí | Identidad del comprobante, descrita en la tabla `infoTributaria`. | | `info` | object | Sí | Cabecera de la nota. Su detalle está en la tabla `info`. | | `motivos` | array | Sí | De 1 a 1000 motivos. Su detalle está en la tabla `motivos`. | | `infoAdicional` | array | No | Hasta 15 objetos `{nombre, valor}`. Su detalle está en la tabla `infoAdicional`. | No envíes `detalles`, `destinatarios` ni `docsSustento`, porque son de otros tipos y la API responde 422 con `Campo no soportado en este contrato.` Tampoco envíes `claveAcceso`, `ambiente`, `tipoEmision`, `version` ni `formato`, porque la API no los admite. ### `infoTributaria` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `ruc` | string | Sí | RUC del emisor, de 5 a 13 dígitos. Debe ser igual a la `identificacion` de la ruta; por ejemplo, `0123456789001`. | | `estab` | string | Sí | Código del [establecimiento](/v1/guias/glosario), de hasta 3 dígitos. Se completa con ceros, así que `"1"` se toma como `"001"`. | | `ptoEmi` | string | Sí | Código del [punto de emisión](/v1/guias/glosario), de hasta 3 dígitos. | | `secuencial` | string | No | Si lo omites o envías `"000000000"`, te asignamos el siguiente número de la serie, que forman `estab`, `ptoEmi`, el tipo `05` y el ambiente. Si envías un número de hasta 9 dígitos, entre 1 y 999999999, usamos ese número. | El tipo de comprobante lo fija la ruta del endpoint, así que `infoTributaria` no lleva `tipoDocumento`. ### `info` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `fechaEmision` | string | Sí | Fecha de la nota, `dd/MM/yyyy`. Envía la fecha de hoy, porque el comprobante autorizado lleva la fecha del día en que se procesa. | | `tipoIdentificacionComprador` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte o `08` identificación del exterior. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). `07`, consumidor final, no se admite. | | `identificacionComprador` | string | Sí | Con `04`, 13 dígitos. Con `05`, 10 dígitos. Con otros tipos, hasta 20 caracteres. | | `razonSocialComprador` | string | Sí | Nombre o razón social del comprador, hasta 300 caracteres. | | `direccionComprador` | string | No | Hasta 300 caracteres. | | `dirEstablecimiento` | string | No | Dirección del establecimiento emisor, hasta 300 caracteres. | | `telefono` | string | No | Teléfono del comprador, hasta 40 caracteres. | | `correo` | string | No | Correo del comprador al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se usa el `infoAdicional` llamado `email` o `correo`. | | `codDocModificado` | string | Sí | Tipo del documento modificado, de 2 dígitos, como `01` para una factura. Los valores están en [Tipos de comprobante](/v1/guias/catalogos#tipos-de-comprobante). | | `numDocModificado` | string | Sí | Número del documento modificado, `ddd-ddd-ddddddddd`, por ejemplo `001-001-000000123`. | | `fechaEmisionDocSustento` | string | Sí | Fecha de emisión del documento modificado, `dd/MM/yyyy`. | | `totalSinImpuestos` | number | Sí | Suma de `motivos[].valor`, con 2 decimales. | | `impuestos` | array | Sí | Exactamente un IVA. Su detalle está en la tabla `info.impuestos`. | | `valorTotal` | number | Sí | `totalSinImpuestos` + IVA, con 2 decimales. | | `moneda` | string | No | `DOLAR` o `USD`. | | `pagos` | array | Sí | De 1 a 20 formas de pago. Su detalle está en la tabla `info.pagos`. | La nota de débito no usa `totalConImpuestos`, `valorModificacion`, `totalDescuento`, `propina` ni `motivo` en singular, y si los envías, la API responde 422 con `Campo no soportado en este contrato.` ### `motivos` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `razon` | string | Sí | Razón del débito, hasta 300 caracteres. La primera razón se usa como motivo del documento. | | `valor` | number | Sí | Importe del motivo **sin IVA**, mayor o igual a 0 y con 2 decimales. | ### `info.impuestos` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codigo` | string | Sí | `"2"`, que es el IVA y el único impuesto admitido en la nota de débito. | | `codigoPorcentaje` | string | Sí | Código de la tarifa de IVA; `"4"` es 15 %. Los valores están en [Tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva). | | `tarifa` | number | Sí | Porcentaje de la tarifa, por ejemplo `15`. Con `codigoPorcentaje` `0`, `6` o `7` envía `0`; con cualquier otro, un valor mayor que 0. | | `baseImponible` | number | Sí | Suma de `motivos[].valor`. | | `valor` | number | Sí | Suma del IVA de cada motivo, calculado y redondeado por motivo. | ### `info.pagos` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `formaPago` | string | Sí | Código de 2 dígitos. Los valores están en [Formas de pago](/v1/guias/catalogos#formas-de-pago). | | `total` | number | Sí | Importe pagado con esa forma. La suma de todos los `total` es igual a `valorTotal`. | | `plazo` | number | No | Número entero mayor o igual a 0. | | `unidadTiempo` | string | Condicional | Obligatoria si `plazo` es mayor que 0, por ejemplo `dias`, con hasta 20 caracteres. | ### `infoAdicional` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `nombre` | string | Sí | Nombre del dato, hasta 300 caracteres. | | `valor` | string | Sí | Valor del dato, hasta 300 caracteres. | Estos datos aparecen en el [RIDE](/v1/guias/glosario), el PDF del comprobante. ## Reglas de cálculo y validaciones Si alguna regla falla, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`), y `errores` describe la regla y, cuando aplica, el campo, como en `$.info: Base o valor de impuestos no coincide con detalles.` Un 422 consume 1 documento como intento, pero no usa un número de la serie, así que corrige el dato y reenvía. | Regla | Ejemplo de incumplimiento | |---|---| | `info.impuestos` lleva un único elemento con `codigo` `"2"`. | Enviar IVA e ICE, o dos tarifas de IVA. | | `totalSinImpuestos` = `impuestos[0].baseImponible` = suma de `motivos[].valor`. | Motivos que suman 30.00 y `totalSinImpuestos` 34.50. | | `impuestos[0].valor` = suma de `redondear(motivo.valor x tarifa / 100, 2)`. | Calcular 4.51 por redondear sobre otro valor. | | `valorTotal` = `totalSinImpuestos` + `impuestos[0].valor`. | `valorTotal` sin el IVA. | | Suma de `pagos[].total` = `valorTotal`. | Pagos por 30.00 con `valorTotal` 34.50. | | Los importes llevan como máximo 2 decimales y la API no los redondea por ti. | `valor: 10.005`. | | El comprador está identificado; no se admite `07`. | Nota de débito a consumidor final. | | `numDocModificado` tiene el formato `ddd-ddd-ddddddddd`. | `001001123`. | | Las fechas van en `dd/MM/yyyy`. | `2026-10-07`. | | Solo se envían los campos de la nota de débito. | Enviar `detalles` o `info.totalConImpuestos`. | ## Respuesta Si la solicitud es válida, la API responde 202 Accepted. El comprobante quedó **recibido**, pero todavía no tiene el resultado del SRI. ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "05", "numeroDocumento": "001-001-000000001", "referenciaExterna": "ND-2026-0001", "claveAcceso": null, "fhRecibido": "2026-11-16T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. | | `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. | | `idOperacion` | string (UUID) | Identificador de la [operación](/v1/guias/glosario). Guárdalo, porque lo necesitas para el seguimiento. | | `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. | Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error. La respuesta trae además estas cabeceras: | Cabecera | Descripción | |---|---| | `Location` | La misma URL completa que `urlEstado`. | | `X-Correlation-Id` | Identificador de correlación de la solicitud. Cítalo al pedir soporte. | Después de recibirla, sigue estos pasos: 1. Guarda `idOperacion` junto a la nota en tu sistema. 2. Consulta `GET /v1/operaciones/{idOperacion}`, como se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion), o espera el [webhook](/v1/guias/webhooks). 3. Cuando su `estado` sea `autorizado`, la operación trae la `claveAcceso` real de 49 dígitos y puedes descargar el RIDE y el XML. Si es `rechazado` o `rechazo_configuracion`, el `codEstado` te dice la causa y `errores` el detalle; corrígela y emite de nuevo con una `Idempotency-Key` nueva y una `referenciaExterna` nueva. Si el `codEstado` es 3001 (`rechazo_sri`), usa además el secuencial automático, como se explica en [Reintentos y duplicados](/v1/guias/emision#reintentos-y-duplicados). ## Estados de este endpoint Esta tabla reúne las respuestas que puedes recibir al emitir una nota de débito. | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 1001 o 1002 | 202 | La nota quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. No reenvíes con otros datos. | | 3003 (`solicitud_invalida`) | 400 | Falta `Idempotency-Key` o no es ASCII de hasta 128 caracteres, o el JSON o el XML está mal formado. | Corrige la solicitud según `errores` y reenvía. | | 3002 (`comprobante_invalido`) | 422 | Falta un campo obligatorio, un campo tiene formato inválido (letras en `estab`, `ruc` fuera de 5 a 13 dígitos, fecha que no es `dd/MM/yyyy`) o no se cumple una regla de la nota (totales, IVA, campos de otro tipo, campo desconocido, `ruc` que no corresponde a la ruta). | Corrige el campo indicado en `errores`. Consume 1 documento como intento. | | 3006 (`cuerpo_excedido`) | 413 | El cuerpo supera 2 MiB. | Reduce `infoAdicional` o el número de motivos. | | 3009 (`credenciales_invalidas`) | 401 | La API Key falta o no es válida. | Revisa `X-Api-Key`. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o revisa proxies entre tu sistema y la API. | | 3011 (`acceso_denegado`) | 403 | El contribuyente de la ruta o el tipo `05` no están habilitados. | Verifica `GET /v1/contexto`; si falta el tipo, solicita habilitarlo. | | 3004 (`comprobante_duplicado`) | 409 | Ya existe una nota de débito con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo. | | 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera lo que indique `Retry-After` y reintenta con la misma `Idempotency-Key`. | | 4004 (`cupo_agotado`) | 429 | Se agotó el cupo de documentos. | Revisa [`GET /v1/consumo`](/v1/guias/consumo) y compra un paquete. | | 5002 (`servicio_no_disponible`) | 503 | El servicio no está disponible temporalmente. | Reintenta con la misma `Idempotency-Key` y el mismo cuerpo. | Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). > [!WARNING] > Ante un timeout, reintenta con la **misma** `Idempotency-Key` y el mismo cuerpo. Cambiar la clave o la `referenciaExterna` puede emitir dos notas de débito. ## Siguientes pasos - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta si el SRI autorizó la nota y obtiene su clave de acceso. - [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar periódicamente. - [Nota de crédito](/v1/guias/emision-04): disminuye el valor de un comprobante en lugar de aumentarlo. - [Catálogos](/v1/guias/catalogos): códigos de identificación, tarifas de IVA y formas de pago. --- # Guía de remisión Emite una guía de remisión, el comprobante que respalda el traslado de mercadería y la acompaña mientras está en tránsito. La guía de remisión documenta quién transporta la mercadería, desde dónde sale, a quién se entrega y qué bienes lleva. Esta guía te da un ejemplo mínimo listo para enviar, explica los límites de este comprobante y describe cada campo con las reglas que valida la API. El endpoint, las cabeceras y las reglas comunes a todos los tipos están en [Comprobantes electrónicos](/v1/guias/emision). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba). Emites la guía de remisión con este endpoint. Para validar el mismo cuerpo sin emitir, usa `POST /v1/contribuyentes/{identificacion}/guias-remision/validar`; la validación aplica las mismas reglas y no consume cupo, como se explica en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). ``` POST /v1/contribuyentes/{identificacion}/guias-remision Cabeceras: X-Api-Key, Idempotency-Key, Content-Type: application/json ``` ## Conceptos - **Transportista**: la persona o empresa que conduce el vehículo. Puede ser tu propio chofer o un tercero. Se identifica con su tipo de identificación, número, razón social y la placa del vehículo. - **Destinatario**: quien recibe la mercadería. Lleva su identificación, dirección de entrega, el motivo del traslado y la lista de bienes (`detalles`). - **Fechas de transporte**: el periodo en que la mercadería está en tránsito. La fecha de inicio (`fechaIniTransporte`) es también la fecha de emisión de la guía; por eso esta guía **no** lleva `fechaEmision`. Los demás términos, como [RUC](/v1/guias/glosario), [establecimiento](/v1/guias/glosario), [secuencial](/v1/guias/glosario), [clave de acceso](/v1/guias/glosario) o [RIDE](/v1/guias/glosario), están explicados en el [Glosario](/v1/guias/glosario). ## Cuándo la emites Emites la guía **antes** de que la mercadería salga. Estos son los casos habituales: - Entregas a un cliente: llevas a su bodega lo que le vendiste. - Trasladas mercadería entre tus propios establecimientos, por ejemplo de la matriz a una sucursal. - Envías mercadería a consignación o a reparación, o la devuelves a un proveedor. La guía no cobra nada: no lleva precios, impuestos, totales ni formas de pago. Si además vendes la mercadería, emite también la [Factura](/v1/guias/emision-01). ## Límites de la guía de remisión La API aplica estos límites a la guía de remisión. | Límite | Qué significa para ti | |---|---| | Un destinatario por guía | `destinatarios` lleva exactamente un elemento. Si repartes a varios clientes, emite una guía por cada uno. | | Destinatario con cédula o RUC | `identificacionDestinatario` tiene 10 dígitos (cédula) o 13 (RUC). Un pasaporte o una identificación del exterior se rechaza. | | Sin documento de sustento por destinatario | No se admiten los campos que asocian el destinatario a una factura (`codDocSustento`, `numDocSustento`, `numAutDocSustento`, `fechaEmisionDocSustento`). Si los envías, la API responde 422 con `Campo no soportado en este contrato.` | | Sin importes | Los `detalles` solo describen bienes y cantidades. | ## Antes de empezar - [ ] Una API Key de pruebas en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea tu sandbox](/v1/guias/sandbox). - [ ] En el ambiente de pruebas puedes llamar desde cualquier IP. En producción, la IP desde la que llamas debe estar registrada para tu API Key, como se explica en [Autenticación](/v1/guias/autenticacion). - [ ] El valor `identificacion` de tu contribuyente, que obtienes con [`GET /v1/contexto`](/v1/guias/consulta-contexto). En los ejemplos es `0123456789001`. - [ ] El tipo `06` habilitado para ese contribuyente, es decir, que aparezca en `tiposComprobante` del contexto. - [ ] Los datos del transportista, la placa, las fechas del traslado y el destinatario. ## Ejemplo mínimo Este ejemplo representa el traslado de dos productos desde la bodega del emisor hasta la bodega de un cliente, del 7 al 8 de octubre de 2026. Guarda el JSON como `comprobante.json`, porque lo usan los ejemplos de [Envío](#envio). ```json { "origenReferencia": "MiERP", "referenciaExterna": "GR-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001", "secuencial": "000000000" }, "info": { "dirPartida": "BODEGA PRINCIPAL DE PRUEBAS", "razonSocialTransportista": "TRANSPORTISTA DE PRUEBAS", "tipoIdentificacionTransportista": "05", "rucTransportista": "0123456789", "fechaIniTransporte": "07/10/2026", "fechaFinTransporte": "08/10/2026", "placa": "PBA0001" }, "destinatarios": [ { "identificacionDestinatario": "0123456789001", "razonSocialDestinatario": "CLIENTE DE PRUEBAS", "dirDestinatario": "BODEGA DEL CLIENTE DE PRUEBAS", "motivoTraslado": "VENTA", "codEstabDestino": "001", "ruta": "QUITO - GUAYAQUIL", "detalles": [ { "codigoInterno": "PROD-001", "descripcion": "CAJA DE PRODUCTO DE PRUEBAS", "cantidad": 10 }, { "codigoInterno": "PROD-002", "descripcion": "REPUESTO DE PRUEBAS", "cantidad": 2.5 } ] } ], "infoAdicional": [ { "nombre": "email", "valor": "cliente@example.com" } ] } ``` Con `"secuencial": "000000000"` te asignamos el siguiente número de la serie 001-001 de guías de remisión, y omitir el campo tiene el mismo efecto. Antes de enviarla, comprueba que la fecha de fin no sea anterior a la de inicio, que cada cantidad sea mayor que 0 y que haya un solo destinatario con al menos un detalle. ## Envío Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`, GR-2026-0001. ```bash curl -s -i -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/guias-remision" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: GR-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/guias-remision"); peticion.Headers.Add("Idempotency-Key", "GR-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/guias-remision", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "GR-2026-0001", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/guias-remision', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'GR-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: GR-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/guias-remision")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "GR-2026-0001") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using System.Text.Json; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); GuiaRemisionRequest comprobante = JsonSerializer.Deserialize( await File.ReadAllTextAsync("comprobante.json"))!; EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "GR-2026-0001"); Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}"); ``` ```python-sdk import json import os from ecuafact import GuiaRemisionRequest, EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) with open("comprobante.json", encoding="utf-8") as archivo: comprobante = GuiaRemisionRequest.model_validate(json.load(archivo)) resultado = client.emitir_en("0123456789001", comprobante, "GR-2026-0001") print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}") ``` ```javascript-sdk // Node.js 18 o superior. Guarda como emitir-sdk.mjs y ejecuta: node emitir-sdk.mjs import { readFile } from 'node:fs/promises'; import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const comprobante = JSON.parse(await readFile('comprobante.json', 'utf8')); const resultado = await client.emitirGuiaRemisionEn('0123456789001', comprobante, 'GR-2026-0001'); console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'GR-2026-0001'); echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.contracts.GuiaRemisionRequest; import com.fasterxml.jackson.databind.ObjectMapper; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); GuiaRemisionRequest comprobante = new ObjectMapper() .readValue(Files.readString(Path.of("comprobante.json")), GuiaRemisionRequest.class); EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "GR-2026-0001"); System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()); ``` ```bash-cli # Resultado esperado: una fila con el estado recibido y el idOperacion de la guía. ecuafact emitir comprobante.json --entorno sandbox ``` Si repites exactamente la misma solicitud, con la misma `Idempotency-Key` y el mismo cuerpo, por ejemplo tras un timeout, la API no crea otra guía. Responde 202 con el mismo `idOperacion` y el estado actual de la operación. ## Estructura del comprobante El cuerpo de la guía de remisión se organiza en bloques, y cada tabla describe uno. ### Raíz | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `origenReferencia` | string | Sí | Nombre de tu sistema de origen, de hasta 64 caracteres entre letras y dígitos ASCII y `- _ . : /`. | | `referenciaExterna` | string | Sí | Identificador estable del documento en tu sistema, de hasta 128 caracteres con el mismo alfabeto. Repítelo igual en cada reintento. | | `infoTributaria` | object | Sí | Identidad del comprobante, descrita en la tabla `infoTributaria`. | | `info` | object | Sí | Datos del traslado y del transportista. Su detalle está en la tabla `info`. | | `destinatarios` | array | Sí | Exactamente un destinatario. Su detalle está en la tabla `destinatarios`. | | `infoAdicional` | array | No | Hasta 15 objetos `{nombre, valor}`. Su detalle está en la tabla `infoAdicional`. | No envíes `detalles` en la raíz, porque van dentro del destinatario, ni `motivos` o `docsSustento`; si lo haces, la API responde 422 con `Campo no soportado en este contrato.` Tampoco envíes `claveAcceso`, `ambiente`, `tipoEmision`, `version` ni `formato`, porque la API no los admite. ### `infoTributaria` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `ruc` | string | Sí | RUC del emisor, de 5 a 13 dígitos. Debe ser igual a la `identificacion` de la ruta; por ejemplo, `0123456789001`. | | `estab` | string | Sí | Código del establecimiento que emite, de hasta 3 dígitos. Se completa con ceros, así que `"1"` se toma como `"001"`. | | `ptoEmi` | string | Sí | Código del [punto de emisión](/v1/guias/glosario), de hasta 3 dígitos. Se completa con ceros. | | `secuencial` | string | No | Si lo omites o envías `"000000000"`, te asignamos el siguiente número de la serie, que forman `estab`, `ptoEmi`, el tipo `06` y el ambiente. Si envías un número de hasta 9 dígitos, entre 1 y 999999999, usamos ese número. | ### `info` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `dirPartida` | string | Sí | Dirección desde donde sale la mercadería, hasta 300 caracteres. | | `razonSocialTransportista` | string | Sí | Nombre o razón social del transportista, hasta 300 caracteres. | | `tipoIdentificacionTransportista` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte o `08` identificación del exterior. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). | | `rucTransportista` | string | Sí | Identificación del transportista. Aunque el nombre del campo dice RUC, sigue al tipo: con `04`, 13 dígitos; con `05`, 10 dígitos; con otros tipos, hasta 20 caracteres. | | `fechaIniTransporte` | string | Sí | Inicio del traslado, `dd/MM/yyyy`. Es también la fecha de emisión de la guía. | | `fechaFinTransporte` | string | Sí | Fin del traslado, `dd/MM/yyyy`. Igual o posterior a `fechaIniTransporte`. | | `placa` | string | Sí | Placa del vehículo, hasta 20 caracteres. | | `dirEstablecimiento` | string | No | Dirección del establecimiento emisor, hasta 300 caracteres. | | `telefono` | string | No | Teléfono del destinatario, hasta 40 caracteres. | | `correo` | string | No | Correo del destinatario al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se usa el `infoAdicional` llamado `email` o `correo`. | La guía no usa `fechaEmision`, `moneda`, `pagos` ni ningún total, y si los envías, la API responde 422 con `Campo no soportado en este contrato.` ### `destinatarios` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `identificacionDestinatario` | string | Sí | Cédula de 10 dígitos o RUC de 13. No necesitas enviar el tipo, porque lo deducimos del largo. | | `razonSocialDestinatario` | string | Sí | Nombre o razón social, hasta 300 caracteres. | | `dirDestinatario` | string | Sí | Dirección de entrega, hasta 300 caracteres. | | `motivoTraslado` | string | Sí | Por qué se traslada la mercadería, como `VENTA`, `TRASLADO ENTRE ESTABLECIMIENTOS` o `DEVOLUCION`, hasta 300 caracteres. | | `codEstabDestino` | string | No | Código del establecimiento de destino del destinatario, de 3 dígitos. | | `ruta` | string | No | Recorrido del traslado, hasta 300 caracteres. No puede ser solo espacios. | | `docAduaneroUnico` | string | No | Número del documento aduanero, si el traslado lo requiere, hasta 20 caracteres. | | `detalles` | array | Sí | De 1 a 1000 bienes. Su detalle está en la tabla `destinatarios[].detalles`. | ### `destinatarios[].detalles` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codigoInterno` | string | Sí | Código del bien en tu sistema, hasta 25 caracteres. | | `codigoAdicional` | string | No | Código adicional del bien. | | `descripcion` | string | Sí | Descripción del bien, hasta 300 caracteres. | | `cantidad` | number | Sí | Cantidad trasladada, mayor que 0. | | `detallesAdicionales` | array | No | Hasta 3 objetos `{nombre, valor}`, como el lote o la serie. | `codigoPrincipal` y `codigoAuxiliar` son de la factura, y si los envías, la API responde 422 con `Campo no soportado en este contrato.` Tampoco envíes `precioUnitario`, `descuento`, `precioTotalSinImpuesto` ni `impuestos`. ### `infoAdicional` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `nombre` | string | Sí | Nombre del dato, hasta 300 caracteres. | | `valor` | string | Sí | Valor del dato, hasta 300 caracteres. | Estos datos aparecen en el [RIDE](/v1/guias/glosario), el PDF del comprobante. ## Validaciones Si alguna regla falla, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`), y `errores` describe la regla y, cuando aplica, el campo, como en `$.destinatarios: Lista vacia, invalida o demasiado extensa.` Un 422 consume 1 documento como intento, pero no usa un número de la serie, así que corrige el dato y reenvía. | Regla | Ejemplo de incumplimiento | |---|---| | `destinatarios` tiene exactamente un elemento. | Dos destinatarios en la misma guía. | | `identificacionDestinatario` tiene 10 o 13 dígitos. | Un pasaporte `AB123456`. | | `fechaFinTransporte` no es anterior a `fechaIniTransporte`. | Inicio `08/10/2026`, fin `07/10/2026`. | | Las fechas van en `dd/MM/yyyy`. | `2026-10-07`. | | Cada detalle tiene `codigoInterno`, `descripcion` y `cantidad` mayor que 0. | `cantidad: 0`, que responde `Guía admite cantidades y no importes ni impuestos.` | | `rucTransportista` coincide con su tipo. | Tipo `04` con 10 dígitos. | | Solo se envían los campos de la guía. | Enviar `info.fechaEmision` o `info.pagos`. | ## Respuesta Si la solicitud es válida, la API responde 202 Accepted. La guía quedó **recibida**, pero todavía no tiene el resultado del SRI. ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "06", "numeroDocumento": "001-001-000000001", "referenciaExterna": "GR-2026-0001", "claveAcceso": null, "fhRecibido": "2026-11-16T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. | | `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. | | `idOperacion` | string (UUID) | Identificador de la [operación](/v1/guias/glosario). Guárdalo, porque lo necesitas para el seguimiento. | | `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. | Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error. La respuesta trae además estas cabeceras: | Cabecera | Descripción | |---|---| | `Location` | La misma URL completa que `urlEstado`. | | `X-Correlation-Id` | Identificador de correlación de la solicitud. Cítalo al pedir soporte. | Después de recibirla, sigue estos pasos: 1. Guarda `idOperacion` junto a la guía en tu sistema. 2. Consulta `GET /v1/operaciones/{idOperacion}`, como se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion), o espera el [webhook](/v1/guias/webhooks). 3. Cuando su `estado` sea `autorizado`, la operación trae la `claveAcceso` real de 49 dígitos y puedes descargar el RIDE para que viaje con la mercadería. Si es `rechazado` o `rechazo_configuracion`, el `codEstado` te dice la causa y `errores` el detalle; corrígela y emite de nuevo con una `Idempotency-Key` nueva y una `referenciaExterna` nueva. Si el `codEstado` es 3001 (`rechazo_sri`), usa además el secuencial automático, como se explica en [Reintentos y duplicados](/v1/guias/emision#reintentos-y-duplicados). ## Estados de este endpoint Esta tabla reúne las respuestas que puedes recibir al emitir una guía de remisión. | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 1001 o 1002 | 202 | La guía quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. No reenvíes con otros datos. | | 3003 (`solicitud_invalida`) | 400 | Falta `Idempotency-Key` o no es ASCII de hasta 128 caracteres, o el JSON o el XML está mal formado. | Corrige la solicitud según `errores` y reenvía. | | 3002 (`comprobante_invalido`) | 422 | Falta un campo obligatorio, un campo tiene formato inválido o no se cumple una regla de la guía (destinatarios, fechas, campos de otro tipo, campo desconocido, `ruc` que no corresponde a la ruta). | Corrige el campo indicado en `errores`. Consume 1 documento como intento. | | 3006 (`cuerpo_excedido`) | 413 | El cuerpo supera 2 MiB. | Reduce el número de detalles o de `infoAdicional`. | | 3009 (`credenciales_invalidas`) | 401 | La API Key falta o no es válida. | Revisa `X-Api-Key`. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o revisa proxies entre tu sistema y la API. | | 3011 (`acceso_denegado`) | 403 | El contribuyente de la ruta o el tipo `06` no están habilitados. | Verifica `GET /v1/contexto`; si falta el tipo, solicita habilitarlo. | | 3004 (`comprobante_duplicado`) | 409 | Ya existe una guía con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo. | | 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera lo que indique `Retry-After` y reintenta con la misma `Idempotency-Key`. | | 4004 (`cupo_agotado`) | 429 | Se agotó el cupo de documentos. | Revisa [`GET /v1/consumo`](/v1/guias/consumo) y compra un paquete. | | 5002 (`servicio_no_disponible`) | 503 | El servicio no está disponible temporalmente. | Reintenta con la misma `Idempotency-Key` y el mismo cuerpo. | Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). > [!WARNING] > Ante un timeout, reintenta con la **misma** `Idempotency-Key` y el mismo cuerpo. Cambiar la clave o la `referenciaExterna` puede emitir dos guías para el mismo traslado. ## Siguientes pasos - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta si el SRI autorizó la guía y obtiene su clave de acceso. - [Descarga del RIDE](/v1/guias/consulta-ride): obtiene el PDF que acompaña a la mercadería. - [Factura](/v1/guias/emision-01): emite la venta de la mercadería que trasladas. - [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar periódicamente. --- # Comprobante de retención Emite un comprobante de retención para acreditar al proveedor los impuestos de renta e IVA que le retuviste al pagarle. Emites el comprobante de retención como agente de retención sobre la factura que te entregó el proveedor, y con él el proveedor descuenta lo retenido de sus propios impuestos. Esta guía explica los conceptos de la retención, te da un ejemplo mínimo listo para enviar y describe cada campo con las reglas que valida la API. Las cabeceras y las reglas comunes a todos los tipos están en [Comprobantes electrónicos](/v1/guias/emision). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba). Envías el comprobante de retención a `POST /v1/contribuyentes/{identificacion}/retenciones`. El tipo de comprobante lo fija la ruta, así que el cuerpo no lleva `infoTributaria.tipoDocumento`. ``` POST /v1/contribuyentes/{identificacion}/retenciones Cabeceras: X-Api-Key, Idempotency-Key, Content-Type: application/json ``` Para revisar el cuerpo sin emitir, usa `POST /v1/contribuyentes/{identificacion}/retenciones/validar`; aplica las mismas reglas y su respuesta se describe en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). ## Conceptos Si nunca antes trabajaste con retenciones en Ecuador, lee esta sección primero. Todos los términos están también en el [Glosario](/v1/guias/glosario). - **Retención**: cuando un contribuyente designado como agente de retención paga una compra, no le entrega al proveedor el 100 %: se queda con un porcentaje del impuesto y lo paga al SRI en nombre del proveedor. - **Retención de renta**: un porcentaje de la base sin IVA, por ejemplo el 10 % en honorarios profesionales. Se identifica con `codigo` `1`. - **Retención de IVA**: un porcentaje del **valor del IVA** de la compra, por ejemplo el 100 % del IVA de los honorarios de una persona natural. Se identifica con `codigo` `2`. - **Documento de sustento**: el comprobante del proveedor sobre el que retienes, normalmente su factura. Lo describes en `docsSustento` con su número, fecha, autorización, totales, impuestos y forma de pago. - **Código de sustento** (`codSustento`): indica para qué usas la compra en tu contabilidad tributaria, por ejemplo `01`, crédito tributario de IVA. - **Periodo fiscal**: el mes y el año en que declaras la retención, con el formato `MM/yyyy`. - **Sujeto retenido**: el proveedor al que le retienes. Ten en cuenta el plazo: la normativa del SRI exige emitir la retención dentro de los 5 días siguientes a recibir el comprobante de venta del proveedor. Te recomendamos controlarlo en tu sistema, porque la API no lo verifica. ## Cuándo lo emites Emite un comprobante de retención en situaciones como estas: - Pagas honorarios a un profesional independiente: retienes renta e IVA. - Compras bienes o servicios a otra empresa y eres agente de retención. - Registras en tu contabilidad una factura de proveedor sobre la que la ley te obliga a retener. ## Límites del comprobante de retención La API aplica estos límites al comprobante de retención. | Límite | Qué significa para ti | |---|---| | Un documento de sustento por retención | `docsSustento` lleva exactamente un elemento. Si retienes sobre varias facturas, emite una retención por factura. | | Solo pago local | `pagoLocExt` debe ser `01`. Los pagos al exterior (`02`) se rechazan. | | Sin dividendos ni reembolsos | `codSustento` `10` (dividendos) y `codDocSustento` `41` (reembolsos) se rechazan con un 422. | | Sin banano | Los códigos de renta `338`, `340`, `341`, `342`, `342A` y `342B` se rechazan con un 422. | | Impuestos retenidos | `retenciones[].codigo` admite `1` (renta), `2` (IVA) y `6` (ISD). | | Campos que no existen | La API no procesa los datos de pago al exterior (`tipoRegi`, `paisEfecPago`, `aplicConvDobTrib`, `pagExtSujRetNorLeg`, `pagoRegFis`), de reembolso (`totalComprobantesReembolso`, `totalBaseImponibleReembolso`, `totalImpuestoReembolso`, `reembolsos`), de dividendos ni de banano (`retenciones[].dividendos`, `retenciones[].compraCajBanano`). Si los envías, la API los rechaza como campos desconocidos. | ## Antes de empezar - [ ] Una API Key de pruebas en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea tu sandbox](/v1/guias/sandbox). - [ ] En el ambiente de pruebas puedes llamar desde cualquier IP. En producción, la IP desde la que llamas debe estar registrada para tu API Key, como se explica en [Autenticación](/v1/guias/autenticacion). - [ ] El valor `identificacion` de tu contribuyente, que obtienes con [`GET /v1/contexto`](/v1/guias/consulta-contexto). En los ejemplos es `0123456789001`. - [ ] El tipo `07` habilitado para ese contribuyente, es decir, que aparezca en `tiposComprobante` del contexto. - [ ] Los datos de la factura del proveedor: número, fecha, totales, impuestos y, si es electrónica, su clave de acceso. - [ ] Los códigos de retención y los porcentajes vigentes que aplican a la compra, que encuentras en [Catálogos: retenciones](/v1/guias/catalogos#retenciones-y-sustento). ## Ejemplo mínimo Este ejemplo es la retención sobre una factura de honorarios profesionales de una persona natural, por 100.00 más IVA 15 %, es decir, 115.00. Retienes el 10 % de renta y el 100 % del IVA. Guarda el JSON como `comprobante.json`, porque lo usan los ejemplos de [Envío](#envio). ```json { "origenReferencia": "MiERP", "referenciaExterna": "RET-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001", "secuencial": "000000000" }, "info": { "fechaEmision": "05/10/2026", "tipoIdentificacionSujetoRetenido": "05", "identificacionSujetoRetenido": "0123456789", "razonSocialSujetoRetenido": "PROVEEDOR DE PRUEBAS", "periodoFiscal": "10/2026", "parteRel": "NO" }, "docsSustento": [ { "codSustento": "01", "codDocSustento": "01", "numDocSustento": "001001000000123", "fechaEmisionDocSustento": "01/10/2026", "fechaRegistroContable": "01/10/2026", "numAutDocSustento": "0110202601012345678900110010010000001231234567814", "pagoLocExt": "01", "totalSinImpuestos": 100.00, "importeTotal": 115.00, "impuestosDocSustento": [ { "codImpuestoDocSustento": "2", "codigoPorcentaje": "4", "baseImponible": 100.00, "tarifa": 15, "valorImpuesto": 15.00 } ], "retenciones": [ { "codigo": "1", "codigoRetencion": "303", "baseImponible": 100.00, "porcentajeRetener": 10, "valorRetenido": 10.00 }, { "codigo": "2", "codigoRetencion": "3", "baseImponible": 15.00, "porcentajeRetener": 100, "valorRetenido": 15.00 } ], "pagos": [ { "formaPago": "20", "total": 115.00 } ] } ], "infoAdicional": [ { "nombre": "email", "valor": "proveedor@example.com" } ] } ``` Con `"secuencial": "000000000"` te asignamos el siguiente número de la serie 001-001 de retenciones, y omitir el campo tiene el mismo efecto. ### Cómo se calcula | Paso | Cálculo | Resultado | Campo | |---|---|---|---| | 1. Base de la factura del proveedor | | 100.00 | `totalSinImpuestos`, `impuestosDocSustento[0].baseImponible` | | 2. IVA de la factura | 100.00 x 15 / 100 | 15.00 | `impuestosDocSustento[0].valorImpuesto` | | 3. Total de la factura | 100.00 + 15.00 | 115.00 | `importeTotal` y suma de `pagos[].total` | | 4. Retención de renta (código `303`, 10 %) sobre la base sin IVA | 100.00 x 10 / 100 | 10.00 | `retenciones[0].valorRetenido` | | 5. Retención de IVA (código `3`, 100 %) sobre el **valor del IVA** | 15.00 x 100 / 100 | 15.00 | `retenciones[1].valorRetenido` | | 6. Total retenido | 10.00 + 15.00 | 25.00 | No se envía; lo calculamos nosotros. | Para el proveedor, el resultado es que de los 115.00 de su factura recibe 90.00 en efectivo o transferencia y 25.00 en el comprobante de retención, que tú pagas al SRI. > [!NOTE] > Los porcentajes de este ejemplo son ilustrativos. Usa los códigos y porcentajes vigentes del SRI para tu caso. En la retención de IVA, la API comprueba que el código exista y que el porcentaje sea el de ese código; en la de renta, solo comprueba que `valorRetenido` sea `baseImponible` x `porcentajeRetener` / 100, y el SRI valida después que el porcentaje corresponda al código. ## Envío Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`, RET-2026-0001. ```bash curl -s -i -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: RET-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json # 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion} ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/retenciones"); peticion.Headers.Add("Idempotency-Key", "RET-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "RET-2026-0001", }, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'RET-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: RET-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Idempotency-Key", "RET-2026-0001") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using System.Text.Json; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); RetencionRequest comprobante = JsonSerializer.Deserialize( await File.ReadAllTextAsync("comprobante.json"))!; EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "RET-2026-0001"); Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}"); ``` ```python-sdk import json import os from ecuafact import RetencionRequest, EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) with open("comprobante.json", encoding="utf-8") as archivo: comprobante = RetencionRequest.model_validate(json.load(archivo)) resultado = client.emitir_en("0123456789001", comprobante, "RET-2026-0001") print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}") ``` ```javascript-sdk // Node.js 18 o superior. Guarda como emitir-sdk.mjs y ejecuta: node emitir-sdk.mjs import { readFile } from 'node:fs/promises'; import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const comprobante = JSON.parse(await readFile('comprobante.json', 'utf8')); const resultado = await client.emitirRetencionEn('0123456789001', comprobante, 'RET-2026-0001'); console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'RET-2026-0001'); echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.contracts.RetencionRequest; import com.fasterxml.jackson.databind.ObjectMapper; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); RetencionRequest comprobante = new ObjectMapper() .readValue(Files.readString(Path.of("comprobante.json")), RetencionRequest.class); EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "RET-2026-0001"); System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()); ``` ```bash-cli # Resultado esperado: una fila con el estado recibido y el idOperacion de la retención. ecuafact emitir comprobante.json --entorno sandbox ``` Si repites exactamente la misma solicitud, con la misma `Idempotency-Key` y el mismo cuerpo, por ejemplo tras un timeout, la API no crea otra retención. Responde 202 con el mismo `idOperacion` y el estado actual de la operación. ## Estructura del comprobante El cuerpo del comprobante de retención se organiza en bloques, y cada tabla describe uno. ### Raíz | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `origenReferencia` | string | Sí | Nombre de tu sistema de origen, de hasta 64 caracteres entre letras y dígitos ASCII y `- _ . : /`. | | `referenciaExterna` | string | Sí | Identificador estable del documento en tu sistema, de hasta 128 caracteres con el mismo alfabeto. Repítelo igual en cada reintento. | | `infoTributaria` | object | Sí | Identidad del comprobante, descrita en la tabla `infoTributaria`. | | `info` | object | Sí | Datos del sujeto retenido y del periodo. Su detalle está en la tabla `info`. | | `docsSustento` | array | Sí | Exactamente un documento de sustento. Su detalle está en la tabla `docsSustento`. | | `infoAdicional` | array | No | Hasta 15 objetos `{nombre, valor}`. Su detalle está en la tabla `infoAdicional`. | No envíes `detalles`, `motivos` ni `destinatarios`, porque la API responde 422 con `Campo no soportado en este contrato.` Tampoco envíes `claveAcceso`, `ambiente`, `tipoEmision`, `version` ni `formato`, porque la API no los admite. ### `infoTributaria` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `ruc` | string | Sí | RUC del emisor, que es el agente de retención, de 5 a 13 dígitos. Debe ser igual a la `identificacion` de la ruta; por ejemplo, `0123456789001`. | | `estab` | string | Sí | Código del [establecimiento](/v1/guias/glosario), de hasta 3 dígitos. Se completa con ceros, así que `"1"` se toma como `"001"`. | | `ptoEmi` | string | Sí | Código del [punto de emisión](/v1/guias/glosario), de hasta 3 dígitos. | | `secuencial` | string | No | Si lo omites o envías `"000000000"`, te asignamos el siguiente número de la serie, que forman `estab`, `ptoEmi`, el tipo del comprobante y el ambiente. Si envías un número de hasta 9 dígitos, entre 1 y 999999999, usamos ese número. | ### `info` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `fechaEmision` | string | Sí | Fecha de la retención, `dd/MM/yyyy`. | | `tipoIdentificacionSujetoRetenido` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte o `08` identificación del exterior. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). `07`, consumidor final, no se admite. | | `identificacionSujetoRetenido` | string | Sí | Con `04`, 13 dígitos. Con `05`, 10 dígitos. Con otros tipos, hasta 20 caracteres. | | `razonSocialSujetoRetenido` | string | Sí | Nombre o razón social del proveedor, hasta 300 caracteres. | | `periodoFiscal` | string | Sí | Mes y año de la declaración, `MM/yyyy`, por ejemplo `10/2026`. | | `parteRel` | string | Sí | `SI` si tú y el proveedor son partes relacionadas; si no, `NO`. | | `tipoSujetoRetenido` | string | No | Clasificación del sujeto retenido, cuando el SRI la exige para una identificación del exterior. | | `dirEstablecimiento` | string | No | Dirección del establecimiento emisor, hasta 300 caracteres. | | `telefono` | string | No | Teléfono del proveedor, hasta 40 caracteres. | | `correo` | string | No | Correo del proveedor al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se usa el `infoAdicional` llamado `email` o `correo`. | La retención no usa `moneda`, `pagos` ni totales en `info`, y si los envías, la API responde 422 con `Campo no soportado en este contrato.` ### `docsSustento` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codSustento` | string | Sí | Código de sustento, de 2 dígitos, que encuentras en [Códigos de sustento](/v1/guias/catalogos#codigos-de-sustento). El `10` se rechaza. | | `codDocSustento` | string | Sí | Tipo del documento de sustento, de 2 dígitos, como `01` para una factura. Los valores están en [Tipos de documento de sustento](/v1/guias/catalogos#tipos-de-documento-de-sustento), y el `41` se rechaza. | | `numDocSustento` | string | Sí | Número de la factura del proveedor, de 15 dígitos sin guiones, como `001001000000123`. También se acepta `ddd-ddd-ddddddddd`. | | `fechaEmisionDocSustento` | string | Sí | Fecha de la factura del proveedor, `dd/MM/yyyy`. | | `fechaRegistroContable` | string | Sí | Fecha en que registraste la factura en tu contabilidad, `dd/MM/yyyy`. | | `numAutDocSustento` | string | No | Número de autorización de la factura del proveedor, de 10 a 49 dígitos; si es electrónica, su clave de acceso de 49 dígitos. | | `pagoLocExt` | string | Sí | `01`, pago local, que es el único valor admitido. | | `totalSinImpuestos` | number | Sí | Base de la factura del proveedor sin impuestos, con 2 decimales. | | `importeTotal` | number | Sí | Total de la factura del proveedor, igual a `totalSinImpuestos` más la suma de `impuestosDocSustento[].valorImpuesto`. | | `impuestosDocSustento` | array | Sí | 1 o 2 impuestos de la factura. Su detalle está en la tabla `docsSustento[].impuestosDocSustento`. | | `retenciones` | array | Sí | De 1 a 1000 retenciones. Su detalle está en la tabla `docsSustento[].retenciones`. | | `pagos` | array | Sí | De 1 a 20 formas de pago de la factura del proveedor. Su detalle está en la tabla `docsSustento[].pagos`. | ### `docsSustento[].impuestosDocSustento` Los impuestos que trae la factura del proveedor, tal como aparecen en ella. | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codImpuestoDocSustento` | string | Sí | Impuesto de la factura, `2` para IVA o `3` para ICE. Los valores están en [Impuestos](/v1/guias/catalogos#impuestos). | | `codigoPorcentaje` | string | Sí | Código de la tarifa; `"4"` es IVA 15 %. Los valores están en [Tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva). | | `baseImponible` | number | Sí | Base del impuesto en la factura, con 2 decimales. | | `tarifa` | number | Sí | Porcentaje de la tarifa, por ejemplo `15`. | | `valorImpuesto` | number | Sí | Valor del impuesto en la factura, con 2 decimales. | ### `docsSustento[].retenciones` Una fila por cada retención que practicas. | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `codigo` | string | Sí | Impuesto retenido, `1` para renta, `2` para IVA o `6` para ISD. | | `codigoRetencion` | string | Sí | Código de la retención dentro de ese impuesto, por ejemplo `303` en renta o `3` en IVA, de hasta 5 caracteres. Los valores están en [Catálogos](/v1/guias/catalogos#retenciones-y-sustento). | | `baseImponible` | number | Sí | Base de la retención. En renta, la base sin IVA; en IVA, el valor del IVA. Lleva 2 decimales. | | `porcentajeRetener` | number | Sí | Porcentaje de retención, de 0 a 100, con 2 decimales como máximo y 3 dígitos en total (`100`, `70`, `10.5` y `2.75` son válidos; `12.75` no). En IVA debe corresponder al `codigoRetencion`. | | `valorRetenido` | number | Sí | `baseImponible` x `porcentajeRetener` / 100, redondeado a 2 decimales. | ### `docsSustento[].pagos` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `formaPago` | string | Sí | Código de 2 dígitos. Los valores están en [Formas de pago](/v1/guias/catalogos#formas-de-pago). | | `total` | number | Sí | Importe pagado con esa forma. La suma de todos los `total` es igual a `importeTotal`. | | `plazo` | number | No | Número entero mayor o igual a 0. | | `unidadTiempo` | string | Condicional | Obligatoria si `plazo` es mayor que 0, por ejemplo `dias`, con hasta 20 caracteres. | ### `infoAdicional` | Campo | Tipo | Obligatorio | Regla | |---|---|---|---| | `nombre` | string | Sí | Nombre del dato, hasta 300 caracteres. | | `valor` | string | Sí | Valor del dato, hasta 300 caracteres. | Estos datos aparecen en el [RIDE](/v1/guias/glosario), el PDF del comprobante. ## Reglas de cálculo y validaciones Si alguna regla falla, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`), y `errores` describe la regla y, cuando aplica, el campo, como en `$.docsSustento[0]: Los totales y pagos del sustento no coinciden.` Un 422 consume 1 documento como intento, pero no usa un número de la serie, así que corrige el dato y reenvía. | Regla | Ejemplo de incumplimiento | |---|---| | `importeTotal` = `totalSinImpuestos` + suma de `impuestosDocSustento[].valorImpuesto`. | `importeTotal` 115.00 con IVA 12.00 y base 100.00. | | Suma de `pagos[].total` = `importeTotal`. | Pagos por 100.00 con `importeTotal` 115.00. | | `valorRetenido` = `redondear(baseImponible x porcentajeRetener / 100, 2)`. | Base 15.00 al 30 % con `valorRetenido` 4.00 (debe ser 4.50). | | `porcentajeRetener` está entre 0 y 100. | `porcentajeRetener: 110`. | | `retenciones[].codigo` es `1`, `2` o `6`. | `codigo: "3"`. | | `docsSustento` tiene exactamente un elemento. | Dos facturas en la misma retención. | | `pagoLocExt` es `01` y `parteRel` es `SI` o `NO`. | `pagoLocExt: "02"`. | | `codSustento` no es `10`, `codDocSustento` no es `41` y no hay códigos de banano. | `codDocSustento: "41"`. | | `periodoFiscal` va en `MM/yyyy` y las fechas en `dd/MM/yyyy`. | `periodoFiscal: "2026-10"`. | | `numAutDocSustento`, si lo envías, tiene de 10 a 49 dígitos. | Autorización de 5 dígitos. | | El sujeto retenido está identificado; no se admite `07`. | Retención a consumidor final. | | Los importes llevan como máximo 2 decimales y la API no los redondea por ti. | `valorRetenido: 10.005`. | ## Respuesta Si la solicitud es válida, la API responde 202 Accepted. La retención quedó **recibida**, pero todavía no tiene el resultado del SRI. ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "07", "numeroDocumento": "001-001-000000001", "referenciaExterna": "RET-2026-0001", "claveAcceso": null, "fhRecibido": "2026-11-16T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. | | `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. | | `idOperacion` | string (UUID) | Identificador de la [operación](/v1/guias/glosario). Guárdalo, porque lo necesitas para el seguimiento. | | `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. | Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error. La respuesta trae además estas cabeceras: | Cabecera | Descripción | |---|---| | `Location` | La misma URL completa que `urlEstado`. | | `X-Correlation-Id` | Identificador de correlación de la solicitud. Cítalo al pedir soporte. | Después de recibirla, sigue estos pasos: 1. Guarda `idOperacion` junto a la retención en tu sistema. 2. Consulta `GET /v1/operaciones/{idOperacion}`, como se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion), o espera el [webhook](/v1/guias/webhooks). 3. Cuando su `estado` sea `autorizado`, la operación trae la `claveAcceso` real de 49 dígitos y puedes descargar el RIDE y el XML para entregarlos al proveedor. Si es `rechazado` o `rechazo_configuracion`, el `codEstado` te dice la causa y `errores` el detalle; corrígela y emite de nuevo con una `Idempotency-Key` nueva y una `referenciaExterna` nueva. Si el `codEstado` es 3001 (`rechazo_sri`), usa además el secuencial automático, como se explica en [Reintentos y duplicados](/v1/guias/emision#reintentos-y-duplicados). ## Estados de este endpoint Esta tabla reúne las respuestas que puedes recibir al emitir un comprobante de retención. | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 1001 o 1002 | 202 | La retención quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. No reenvíes con otros datos. | | 3003 (`solicitud_invalida`) | 400 | Falta `Idempotency-Key` o no es ASCII de hasta 128 caracteres, o el JSON o el XML está mal formado. | Corrige la solicitud según `errores` y reenvía. | | 3002 (`comprobante_invalido`) | 422 | Falta un campo obligatorio, un campo tiene formato inválido o no se cumple una regla de la retención (totales del sustento, cálculo de la retención, límites del comprobante de retención, campo desconocido, `ruc` que no corresponde a la ruta). | Corrige el campo indicado en `errores`. Consume 1 documento como intento. | | 3006 (`cuerpo_excedido`) | 413 | El cuerpo supera 2 MiB. | Reduce el número de retenciones o de `infoAdicional`. | | 3009 (`credenciales_invalidas`) | 401 | La API Key falta o no es válida. | Revisa `X-Api-Key`. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o revisa proxies entre tu sistema y la API. | | 3011 (`acceso_denegado`) | 403 | El contribuyente de la ruta o el tipo `07` no están habilitados. | Verifica `GET /v1/contexto`; si falta el tipo, solicita habilitarlo. | | 3004 (`comprobante_duplicado`) | 409 | Ya existe una retención con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo. | | 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera lo que indique `Retry-After` y reintenta con la misma `Idempotency-Key`. | | 4004 (`cupo_agotado`) | 429 | Se agotó el cupo de documentos. | Revisa [`GET /v1/consumo`](/v1/guias/consumo) y compra un paquete. | | 5002 (`servicio_no_disponible`) | 503 | El servicio no está disponible temporalmente. | Reintenta con la misma `Idempotency-Key` y el mismo cuerpo. | Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). > [!WARNING] > Ante un timeout, reintenta con la **misma** `Idempotency-Key` y el mismo cuerpo. Cambiar la clave o la `referenciaExterna` puede emitir dos retenciones sobre la misma factura. ## Siguientes pasos - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta si el SRI autorizó la retención y obtiene su clave de acceso. - [Catálogos](/v1/guias/catalogos#retenciones-y-sustento): códigos de retención, de sustento y tipos de documento de sustento. - [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar periódicamente. - [Liquidación de compra](/v1/guias/emision-03): documenta compras a proveedores que no emiten factura. --- # Descargar PDF Descarga el RIDE, el PDF de un comprobante emitido, a partir de su clave de acceso. El [RIDE](/v1/guias/glosario) es la representación impresa del comprobante electrónico, es decir, el PDF que entregas o envías a tu cliente. Con este endpoint puedes descargarlo a partir de la [clave de acceso](/v1/guias/glosario) del comprobante, para guardarlo en tu sistema, mostrarlo o adjuntarlo donde lo necesites. Al terminar esta página sabrás cuándo está disponible el RIDE, cómo descargarlo sin confundir un error con un PDF y qué hacer si todavía no está listo. ``` GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride X-Api-Key: ``` ## Cuándo usarlo Te recomendamos descargar el RIDE cuando el `estado` de la operación sea `autorizado`, algo que sabes por el [seguimiento](/v1/guias/consulta-operacion) o por el webhook `document.authorized`. Si vas a mostrarlo o reenviarlo varias veces, guárdalo en tu sistema en lugar de pedirlo cada vez. Puedes descargar el RIDE en cuanto la operación tiene `claveAcceso`, aunque su `estado` todavía sea `recibido`. Mientras la operación no tiene clave de acceso, la API responde 404 con el `codEstado` 3013 (`no_encontrado`). Te entregamos el PDF aunque el comprobante todavía no esté autorizado, pero solo el RIDE de un comprobante `autorizado` tiene validez fiscal. Si lo pides antes y recibes un 404, espera el resultado y vuelve a pedirlo. Un contribuyente de marca blanca, con `marcaBlanca` en `true` en [`GET /v1/contexto`](/v1/guias/consulta-contexto), no tiene RIDE: la API responde siempre 404 con el `codEstado` 3013 (`no_encontrado`) para sus comprobantes, aunque estén autorizados. Para esos comprobantes descarga el [XML autorizado](/v1/guias/consulta-xml) y genera tu propia representación impresa si la necesitas. Revisa `marcaBlanca` antes de pedir el RIDE para no reintentar un 404 que no va a cambiar. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). - [ ] La `identificacion` del contribuyente emisor, que obtienes con [`GET /v1/contexto`](/v1/guias/consulta-contexto). Es la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos. - [ ] La `claveAcceso` de 49 dígitos del comprobante, que te dan el [seguimiento](/v1/guias/consulta-operacion), el webhook o el [listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente). ## Parámetros | Nombre | Tipo | Obligatorio | Descripción | |---|---|---|---| | `identificacion` (ruta) | string | Sí | Identificación del contribuyente emisor tal como la devuelve [`GET /v1/contexto`](/v1/guias/consulta-contexto) en `identificacion`; es la identificación completa del contribuyente, la misma de `infoTributaria.ruc`. | | `claveAcceso` (ruta) | string | Sí | Clave de acceso de 49 dígitos del comprobante, tal como la devuelven el seguimiento o el webhook. Debe tener su dígito verificador correcto. | | `X-Api-Key` (cabecera) | string | Sí | Tu API Key. | ## Ejemplo > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Cada ejemplo comprueba que la respuesta sea 200 y solo entonces guarda el cuerpo; los ejemplos de código lo guardan como `ride.pdf` y el CLI como `{claveAcceso}.pdf`. Si la respuesta es un error, el cuerpo es JSON, así que los ejemplos lo imprimen en lugar de guardarlo y no terminas con un PDF que no abre. Reemplaza la clave de ejemplo por la de tu comprobante. ```bash CODIGO=$(curl -s -o ride.pdf -w "%{http_code}" \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride" \ -H "X-Api-Key: $ECUAFACT_API_KEY") if [ "$CODIGO" = "200" ]; then echo "200 RIDE guardado en ride.pdf"; else echo "$CODIGO $(cat ride.pdf)"; rm ride.pdf; fi ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync( "/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride"); if ((int)respuesta.StatusCode == 200) { byte[] pdf = await respuesta.Content.ReadAsByteArrayAsync(); await File.WriteAllBytesAsync("ride.pdf", pdf); Console.WriteLine($"200 RIDE guardado en ride.pdf ({pdf.Length} bytes)"); } else { Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); } ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=60, ) if r.status_code == 200: with open("ride.pdf", "wb") as archivo: archivo.write(r.content) print(200, "RIDE guardado en ride.pdf", len(r.content), "bytes") else: print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como ride.mjs y ejecuta: node ride.mjs import { writeFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); if (res.status === 200) { const pdf = Buffer.from(await res.arrayBuffer()); await writeFile('ride.pdf', pdf); console.log(200, `RIDE guardado en ride.pdf (${pdf.length} bytes)`); } else { console.log(res.status, await res.text()); } ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($estado === 200) { file_put_contents('ride.pdf', $cuerpo); echo '200 RIDE guardado en ride.pdf (' . strlen($cuerpo) . ' bytes)' . PHP_EOL; } else { echo $estado . ' ' . $cuerpo . PHP_EOL; } ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofByteArray()); if (respuesta.statusCode() == 200) { Files.write(Path.of("ride.pdf"), respuesta.body()); System.out.println("200 RIDE guardado en ride.pdf (" + respuesta.body().length + " bytes)"); } else { System.out.println(respuesta.statusCode() + " " + new String(respuesta.body(), StandardCharsets.UTF_8)); } ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); // Si la API responde un error, el SDK lanza EcuafactApiException. ArchivoComprobante ride = await client.DescargarRideAsync("0123456789001", "0710202601012345678900110010010000001231234567811"); await File.WriteAllBytesAsync("ride.pdf", ride.Contenido); Console.WriteLine($"RIDE guardado en ride.pdf ({ride.Contenido.Length} bytes, {ride.ContentType})"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) # Si la API responde un error, el SDK lanza EcuafactApiException. archivo = client.descargar_ride("0123456789001", "0710202601012345678900110010010000001231234567811") with open("ride.pdf", "wb") as destino: destino.write(archivo.contenido) print("RIDE guardado en ride.pdf", len(archivo.contenido), "bytes") ``` ```javascript-sdk // Node.js 18 o superior. Guarda como ride-sdk.mjs y ejecuta: node ride-sdk.mjs import { writeFile } from 'node:fs/promises'; import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); // Si la API responde un error, el SDK lanza EcuafactApiException. const archivo = await client.descargarRide('0123456789001', '0710202601012345678900110010010000001231234567811'); await writeFile('ride.pdf', archivo.contenido); console.log(`RIDE guardado en ride.pdf (${archivo.contenido.length} bytes)`); ``` ```php-sdk descargarRide('0123456789001', '0710202601012345678900110010010000001231234567811'); file_put_contents('ride.pdf', $archivo->contenido); echo 'RIDE guardado en ride.pdf (' . strlen($archivo->contenido) . ' bytes)' . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.ArchivoComprobante; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); // Si la API responde un error, el SDK lanza EcuafactApiException. ArchivoComprobante archivo = client.descargarRide("0123456789001", "0710202601012345678900110010010000001231234567811"); Files.write(Path.of("ride.pdf"), archivo.contenido()); System.out.println("RIDE guardado en ride.pdf (" + archivo.contenido().length + " bytes)"); ``` ```bash-cli # Resultado esperado: el RIDE descargado como 0710202601012345678900110010010000001231234567811.pdf en la carpeta actual. ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo ride --entorno sandbox ``` Sabrás que funcionó si el archivo que guardó el ejemplo abre en un lector de PDF y muestra el comprobante. ## Respuesta La API responde `200 OK` con el PDF como cuerpo binario: | Elemento | Valor | |---|---| | Estado HTTP | 200 | | `Content-Type` | `application/pdf` | | Cuerpo | Bytes del PDF. No es JSON ni texto, así que guárdalo como archivo binario y no lo imprimas en consola ni lo conviertas a texto. | La respuesta no trae un nombre de archivo. Te sugerimos guardarlo como `{claveAcceso}.pdf` para encontrarlo después. Si la respuesta no es 200, el cuerpo es un error JSON: ```json { "estado": "rechazado", "codEstado": 3013, "msgError": "Recurso no encontrado.", "errores": [] } ``` ## Estados de este endpoint | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | El cuerpo trae el PDF del RIDE. | Guárdalo como archivo binario. | | 3003 (`solicitud_invalida`) | 400 | La `claveAcceso` no tiene 49 dígitos, tiene un dígito verificador incorrecto o es solo ceros. El campo `errores` trae el detalle. | Copia la clave del seguimiento o del webhook. | | 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. | | 3011 (`acceso_denegado`) | 403 | El contribuyente no está habilitado para tu API Key en este ambiente, o tu API Key está limitada y no incluye el scope `comprobantes:leer`. | Usa la `identificacion` que devuelve [`/v1/contexto`](/v1/guias/consulta-contexto). | | 3013 (`no_encontrado`) | 404 | No existe un comprobante emitido con esa clave para ese contribuyente y ambiente, el PDF todavía no está disponible o el contribuyente es de marca blanca (`marcaBlanca` en `true` en [`/v1/contexto`](/v1/guias/consulta-contexto)) y no tiene RIDE. | Si el contribuyente es de marca blanca, no reintentes: descarga el [XML](/v1/guias/consulta-xml). Si acabas de emitir, espera a que el `estado` de la operación sea `autorizado` y reintenta. Si persiste, revisa la clave y el ambiente, de pruebas o de producción. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes. | Espera lo que indica `Retry-After` y reintenta. | | 5003 (`error_dependencia`) | 502 | Nuestro servicio que genera el PDF devolvió un error. | Reintenta en unos minutos con una espera creciente. | | 5001 (`error_interno`) | 500 | Ocurrió un error inesperado, por ejemplo una falla de comunicación con nuestro servicio que genera el PDF. | Reintenta en unos minutos y, si persiste, contacta a soporte con el valor de la cabecera `X-Correlation-Id`. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Descargar XML](/v1/guias/consulta-xml): obtén el XML autorizado, que es el documento con validez legal. - [Perfil del emisor](/v1/guias/perfil-emisor): cambia el logo y los datos de contacto que aparecen en el RIDE. --- # Descargar XML Descarga el XML autorizado de un comprobante emitido a partir de su clave de acceso. El XML es el comprobante electrónico en sí: el documento que el SRI valida y el que debes conservar en tu archivo contable. El [RIDE](/v1/guias/glosario), en cambio, es solo su representación impresa en PDF. Con este endpoint puedes descargar el XML a partir de la [clave de acceso](/v1/guias/glosario) del comprobante. Al terminar esta página sabrás cuándo está disponible el XML y cómo descargarlo sin volver a emitir el comprobante. ``` GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml X-Api-Key: ``` ## Cuándo usarlo Te recomendamos descargar el XML cuando el `estado` de la operación sea `autorizado`, algo que sabes por el [seguimiento](/v1/guias/consulta-operacion) o por el webhook `document.authorized`, y guardarlo junto con la clave de acceso. La API responde `200` cuando el comprobante está autorizado y su XML está disponible. Mientras falta la autorización o el archivo, responde HTTP `404` con el `codEstado` 3013 (`no_encontrado`). Espera y repite esta consulta; no vuelvas a emitir. Si persiste, revisa la clave, el contribuyente y el ambiente. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). - [ ] La `identificacion` del contribuyente emisor, que obtienes con [`GET /v1/contexto`](/v1/guias/consulta-contexto). Es la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos. - [ ] La `claveAcceso` de 49 dígitos del comprobante, que te dan el [seguimiento](/v1/guias/consulta-operacion), el webhook o el [listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente). ## Parámetros | Nombre | Tipo | Obligatorio | Descripción | |---|---|---|---| | `identificacion` (ruta) | string | Sí | Identificación del contribuyente emisor tal como la devuelve [`GET /v1/contexto`](/v1/guias/consulta-contexto) en `identificacion`; es la identificación completa del contribuyente, la misma de `infoTributaria.ruc`. | | `claveAcceso` (ruta) | string | Sí | Clave de acceso de 49 dígitos del comprobante, tal como la devuelven el seguimiento o el webhook. Debe tener su dígito verificador correcto. | | `X-Api-Key` (cabecera) | string | Sí | Tu API Key. | ## Ejemplo > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Cada ejemplo comprueba que la respuesta sea 200 y solo guarda el XML; los ejemplos de código lo guardan como `comprobante.xml` y el CLI como `{claveAcceso}.xml`. Si la respuesta es un error, los ejemplos imprimen el JSON del error en lugar de guardarlo. Reemplaza la clave de ejemplo por la de tu comprobante. ```bash CODIGO=$(curl -s -o comprobante.xml -w "%{http_code}" \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml" \ -H "X-Api-Key: $ECUAFACT_API_KEY") if [ "$CODIGO" != "200" ]; then echo "$CODIGO $(cat comprobante.xml)"; rm comprobante.xml else echo "200 XML guardado en comprobante.xml"; fi ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync( "/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml"); if ((int)respuesta.StatusCode != 200) { Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); return; } byte[] xml = await respuesta.Content.ReadAsByteArrayAsync(); await File.WriteAllBytesAsync("comprobante.xml", xml); Console.WriteLine($"200 XML guardado en comprobante.xml ({xml.Length} bytes)"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=60, ) if r.status_code != 200: print(r.status_code, r.text) else: with open("comprobante.xml", "wb") as archivo: archivo.write(r.content) print(200, "XML guardado en comprobante.xml", len(r.content), "bytes") ``` ```javascript // Node.js 18 o superior. Guarda como xml.mjs y ejecuta: node xml.mjs import { writeFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); if (res.status !== 200) { console.log(res.status, await res.text()); } else { const xml = Buffer.from(await res.arrayBuffer()); await writeFile('comprobante.xml', xml); console.log(200, `XML guardado en comprobante.xml (${xml.length} bytes)`); } ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($estado !== 200) { echo $estado . ' ' . $cuerpo . PHP_EOL; } else { file_put_contents('comprobante.xml', $cuerpo); echo '200 XML guardado en comprobante.xml (' . strlen($cuerpo) . ' bytes)' . PHP_EOL; } ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofByteArray()); if (respuesta.statusCode() != 200) { System.out.println(respuesta.statusCode() + " " + new String(respuesta.body(), StandardCharsets.UTF_8)); } else { Files.write(Path.of("comprobante.xml"), respuesta.body()); System.out.println("200 XML guardado en comprobante.xml (" + respuesta.body().length + " bytes)"); } ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); // Si la API responde un error, el SDK lanza EcuafactApiException. ArchivoComprobante xml = await client.DescargarXmlAsync("0123456789001", "0710202601012345678900110010010000001231234567811"); await File.WriteAllBytesAsync("comprobante.xml", xml.Contenido); Console.WriteLine($"XML guardado en comprobante.xml ({xml.Contenido.Length} bytes)"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) # Si la API responde un error, el SDK lanza EcuafactApiException. archivo = client.descargar_xml("0123456789001", "0710202601012345678900110010010000001231234567811") with open("comprobante.xml", "wb") as destino: destino.write(archivo.contenido) print("XML guardado en comprobante.xml", len(archivo.contenido), "bytes") ``` ```javascript-sdk // Node.js 18 o superior. Guarda como xml-sdk.mjs y ejecuta: node xml-sdk.mjs import { writeFile } from 'node:fs/promises'; import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); // Si la API responde un error, el SDK lanza EcuafactApiException. const archivo = await client.descargarXml('0123456789001', '0710202601012345678900110010010000001231234567811'); await writeFile('comprobante.xml', archivo.contenido); console.log(`XML guardado en comprobante.xml (${archivo.contenido.length} bytes)`); ``` ```php-sdk descargarXml('0123456789001', '0710202601012345678900110010010000001231234567811'); file_put_contents('comprobante.xml', $archivo->contenido); echo 'XML guardado en comprobante.xml' . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.ArchivoComprobante; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); // Si la API responde un error, el SDK lanza EcuafactApiException. ArchivoComprobante archivo = client.descargarXml("0123456789001", "0710202601012345678900110010010000001231234567811"); Files.write(Path.of("comprobante.xml"), archivo.contenido()); System.out.println("XML guardado en comprobante.xml"); ``` ```bash-cli # Resultado esperado: el XML descargado como 0710202601012345678900110010010000001231234567811.xml. # Si el XML aun no esta disponible, la API devuelve HTTP 404; reintenta la descarga mas tarde. ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo xml --entorno sandbox ``` Sabrás que funcionó si el archivo que guardó el ejemplo se abre como XML y contiene la clave de acceso que pediste. ## Respuesta La API responde `200 OK` con el XML como cuerpo: | Elemento | Valor | |---|---| | Estado HTTP | 200 | | `Content-Type` | `application/xml` | | `Content-Disposition` | `attachment`, con el nombre de archivo `{claveAcceso}.xml`. | | Cuerpo | El XML del comprobante. Guárdalo tal cual, sin reformatearlo ni cambiar su codificación, porque cualquier cambio invalida la firma electrónica. | Si la respuesta no es 200, el cuerpo es un error JSON: ```json { "estado": "rechazado", "codEstado": 3013, "msgError": "Recurso no encontrado.", "errores": [] } ``` ## XML todavía no disponible El XML se entrega únicamente cuando el comprobante está autorizado. Mientras el archivo autorizado no esté disponible, la API responde 404 con el `codEstado` 3013 (`no_encontrado`). Cuando eso ocurra, consulta el [seguimiento de la operación](/v1/guias/consulta-operacion) y vuelve a pedir el XML cuando el `estado` sea `autorizado`. ## Estados de este endpoint | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | El cuerpo trae el XML autorizado. | Guarda el archivo sin modificarlo. | | 3003 (`solicitud_invalida`) | 400 | La `claveAcceso` no tiene 49 dígitos, tiene un dígito verificador incorrecto o es solo ceros. El campo `errores` trae el detalle. | Copia la clave del seguimiento o del webhook. | | 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. | | 3011 (`acceso_denegado`) | 403 | El contribuyente no está habilitado para tu API Key en este ambiente, o tu API Key está limitada y no incluye el scope `comprobantes:leer`. | Usa la `identificacion` que devuelve [`/v1/contexto`](/v1/guias/consulta-contexto). | | 3013 (`no_encontrado`) | 404 | No existe el comprobante para ese contribuyente y ambiente, o falta su autorización o el archivo. | Consulta la operación y reintenta la descarga. No vuelvas a emitir. Si persiste, revisa la clave y el ambiente. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes. | Espera lo que indica `Retry-After` y reintenta. | | 5003 (`error_dependencia`) | 502 | Nuestro servicio que entrega el XML devolvió un error. | Reintenta en unos minutos con una espera creciente. | | 5001 (`error_interno`) | 500 | Ocurrió un error inesperado, por ejemplo una falla de comunicación con nuestro servicio que entrega el XML. | Reintenta en unos minutos y, si persiste, contacta a soporte con el valor de la cabecera `X-Correlation-Id`. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Descargar PDF](/v1/guias/consulta-ride): obtén el RIDE para entregarlo a tu cliente. - [Listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente): encuentra la clave de acceso de comprobantes anteriores. --- # Perfil del emisor Lee y actualiza los datos del emisor que aparecen en el RIDE, como el nombre comercial, la dirección y el contacto, y cambia su logo. El perfil del emisor reúne los datos que mostramos en el [RIDE](/v1/guias/glosario), el PDF del comprobante, y en el correo que enviamos al comprador. Con estos tres endpoints puedes leer ese perfil, cambiar los datos de contacto y subir el logo que se imprime en el RIDE. Esta página explica cada operación con sus ejemplos, la respuesta campo a campo y los errores posibles. Al terminar tendrás el perfil listo para que tus comprobantes muestren los datos correctos. ``` GET /v1/contribuyentes/{identificacion}/perfil PUT /v1/contribuyentes/{identificacion}/perfil POST /v1/contribuyentes/{identificacion}/perfil/logo X-Api-Key: ``` ## Cuándo usarlo El perfil del [emisor](/v1/guias/glosario) incluye el nombre comercial, la dirección matriz, el correo, el teléfono, la ciudad, la provincia y el logo. Puedes usar cada operación según lo que necesites: - **GET**: para mostrar en tu sistema los datos que verán tus clientes, o para revisar el perfil antes de emitir por primera vez. - **PUT**: para actualizar el perfil cuando el emisor cambia de dirección, teléfono o correo de contacto. - **POST logo**: para poner o cambiar el logo del RIDE. Puedes leer los datos fiscales, como la razón social, el RUC, la obligación de llevar contabilidad y el establecimiento y el punto de emisión configurados, pero no cambiarlos por esta vía. Estas operaciones no consumen cupo. ## Antes de empezar - [ ] Una API Key en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea tu sandbox](/v1/guias/sandbox). - [ ] Solo en producción, la IP desde la que llamas registrada para tu integración, como se explica en [Autenticación](/v1/guias/autenticacion#registra-tu-ip). El sandbox acepta cualquier IP. - [ ] La `identificacion` del contribuyente, que obtienes de [`GET /v1/contexto`](/v1/guias/consulta-contexto). En los ejemplos es `0123456789001`. - [ ] Para cambiar el logo, un archivo `logo.png` o JPEG de hasta 512 KB en la carpeta desde la que ejecutas el ejemplo. ## Parámetros comunes Las tres operaciones usan estos parámetros. | Nombre | Tipo | Obligatorio | Descripción | |---|---|---|---| | `identificacion` (ruta) | string | Sí | Identificación del contribuyente tal como la devuelve [`GET /v1/contexto`](/v1/guias/consulta-contexto) en `identificacion`; es la identificación completa del contribuyente, la misma de `infoTributaria.ruc`. | | `X-Api-Key` (cabecera) | string | Sí | Tu API Key. | ## Leer el perfil Lee el perfil para ver los datos que aparecen hoy en el RIDE de tus comprobantes. ``` GET /v1/contribuyentes/{identificacion}/perfil ``` > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/contribuyentes/0123456789001/perfil"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como perfil.mjs y ejecuta: node perfil.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); PerfilEmisor perfil = await client.GetPerfilAsync("0123456789001"); Console.WriteLine($"{perfil.RazonSocial} / {perfil.NombreComercial} / {perfil.Correo}"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) perfil = client.get_perfil("0123456789001") print(perfil.razon_social, "/", perfil.nombre_comercial, "/", perfil.correo) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como perfil-sdk.mjs y ejecuta: node perfil-sdk.mjs import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const perfil = await client.getPerfil('0123456789001'); console.log(perfil.razonSocial, '/', perfil.nombreComercial, '/', perfil.correo); ``` ```php-sdk getPerfil('0123456789001'); echo $perfil->razonSocial . ' / ' . $perfil->nombreComercial . ' / ' . $perfil->correo . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.PerfilEmisor; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); PerfilEmisor perfil = client.getPerfil("0123456789001"); System.out.println(perfil.razonSocial + " / " + perfil.nombreComercial + " / " + perfil.correo); ``` ```bash-cli # Resultado esperado: el perfil del emisor, con los datos que aparecen en el RIDE. ecuafact perfil-emisor ver --entorno sandbox ``` ### Respuesta La API responde 200 OK con el perfil del emisor en el primer nivel del JSON. Las tres operaciones, leer, actualizar y cambiar el logo, devuelven esta misma forma, con los datos vigentes después del cambio. ```json { "identificacion": "0123456789001", "razonSocial": "EMPRESA DE PRUEBA S.A.", "nombreComercial": "Prueba", "direccionMatriz": "Av. Principal 123", "direccionEstablecimiento": "Av. Principal 123", "codigoEstablecimiento": "001", "codigoPuntoEmision": "001", "moneda": "DOLAR", "obligadoContabilidad": true, "correo": "contacto@ejemplo.com", "telefono": "042345678", "ciudad": "GUAYAQUIL", "provincia": "GUAYAS", "pais": "ECUADOR", "logo": "0123456789001_Logo.jpg" } ``` | Campo | Tipo | Editable | Descripción | |---|---|---|---| | `identificacion` | string | No | Identificación completa del emisor, la misma de `infoTributaria.ruc`. | | `razonSocial` | string | No | Razón social registrada en el SRI. | | `nombreComercial` | string o `null` | Sí | Nombre comercial que aparece en el RIDE. | | `direccionMatriz` | string o `null` | Sí | Dirección de la matriz. | | `direccionEstablecimiento` | string o `null` | No | Dirección del [establecimiento](/v1/guias/glosario) configurado. | | `codigoEstablecimiento` | string o `null` | No | Código del establecimiento configurado, de 3 dígitos. | | `codigoPuntoEmision` | string o `null` | No | Código del [punto de emisión](/v1/guias/glosario) configurado, de 3 dígitos. | | `moneda` | string o `null` | No | Moneda configurada. | | `obligadoContabilidad` | boolean | No | `true` si el emisor está obligado a llevar contabilidad. | | `correo` | string o `null` | Sí | Correo de contacto del emisor. | | `telefono` | string o `null` | Sí | Teléfono de contacto. | | `ciudad` | string o `null` | Sí | Ciudad. | | `provincia` | string o `null` | Sí | Provincia. | | `pais` | string o `null` | No | País. | | `logo` | string o `null` | Por `POST .../logo` | Referencia del logo registrado, o `null` si no hay logo. No es una URL descargable. | ## Actualizar el perfil ``` PUT /v1/contribuyentes/{identificacion}/perfil Content-Type: application/json ``` Envía solo los campos que quieres cambiar. Un campo que omites o envías como `null` conserva su valor actual. | Campo | Tipo | Obligatorio | Descripción | |---|---|---|---| | `nombreComercial` | string | No | Nuevo nombre comercial, hasta 300 caracteres. | | `direccionMatriz` | string | No | Nueva dirección de la matriz, hasta 300 caracteres. Si se envía, no puede quedar vacía ni contener solo espacios. | | `correo` | string | No | Una dirección de correo válida, hasta 200 caracteres. | | `telefono` | string | No | Nuevo teléfono, hasta 50 caracteres. | | `ciudad` | string | No | Nueva ciudad, hasta 100 caracteres. | | `provincia` | string | No | Nueva provincia, hasta 100 caracteres. | Los textos deben ocupar una sola línea, sin caracteres de control ni separadores Unicode de línea o párrafo. Los campos opcionales admiten `""` para vaciarlos; `direccionMatriz` debe conservar una dirección. Si un campo no cumple estas reglas, la respuesta es 400 con `codEstado` 3003 y el campo indicado en `errores`. > [!NOTE] > Solo se aceptan estos seis campos. Si envías otro, como `razonSocial` o > `logo`, la API responde 400 con el `codEstado` 3003 (`solicitud_invalida`) y no cambia nada. Un texto vacío > (`""`) no equivale a omitir el campo, porque se envía como valor nuevo. Guarda este JSON como `perfil.json`. Los ejemplos lo envían para cambiar el nombre comercial, el correo y el teléfono. ```json { "nombreComercial": "Prueba", "correo": "contacto@ejemplo.com", "telefono": "042345678" } ``` ```bash curl -s -X PUT "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Content-Type: application/json" \ -d @perfil.json ``` ```csharp using System.Net.Http; using System.Text; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Put, "/v1/contribuyentes/0123456789001/perfil"); peticion.Content = new StringContent( await File.ReadAllTextAsync("perfil.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import json import os import requests with open("perfil.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.put( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, json=cuerpo, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como actualizar-perfil.mjs y ejecuta: node actualizar-perfil.mjs import { readFile } from 'node:fs/promises'; const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil', { method: 'PUT', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Content-Type': 'application/json' }, body: await readFile('perfil.json', 'utf8') }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_CUSTOMREQUEST => 'PUT', CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('perfil.json'), ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Content-Type", "application/json") .PUT(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("perfil.json")))) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); PerfilEmisor perfil = await client.ActualizarPerfilAsync("0123456789001", new PerfilEmisorUpdate { NombreComercial = "Prueba", Correo = "contacto@ejemplo.com", Telefono = "042345678" }); Console.WriteLine($"{perfil.NombreComercial} / {perfil.Correo}"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions from ecuafact.models import PerfilEmisorUpdate client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) cambios = PerfilEmisorUpdate(nombre_comercial="Prueba", correo="contacto@ejemplo.com", telefono="042345678") perfil = client.actualizar_perfil("0123456789001", cambios) print(perfil.nombre_comercial, "/", perfil.correo) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como actualizar-perfil-sdk.mjs y ejecuta: node actualizar-perfil-sdk.mjs import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const perfil = await client.actualizarPerfil('0123456789001', { nombreComercial: 'Prueba', correo: 'contacto@ejemplo.com', telefono: '042345678' }); console.log(perfil.nombreComercial, '/', perfil.correo); ``` ```php-sdk nombreComercial = 'Prueba'; $cambios->correo = 'contacto@ejemplo.com'; $cambios->telefono = '042345678'; $perfil = $client->actualizarPerfil('0123456789001', $cambios); echo $perfil->nombreComercial . ' / ' . $perfil->correo . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.PerfilEmisor; import com.ecuafact.sdk.contracts.PerfilEmisorUpdate; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); PerfilEmisorUpdate cambios = new PerfilEmisorUpdate(); cambios.nombreComercial = "Prueba"; cambios.correo = "contacto@ejemplo.com"; cambios.telefono = "042345678"; PerfilEmisor perfil = client.actualizarPerfil("0123456789001", cambios); System.out.println(perfil.nombreComercial + " / " + perfil.correo); ``` ```bash-cli # Resultado esperado: el perfil completo, con el nombre comercial, el correo y el teléfono nuevos. ecuafact perfil-emisor editar --nombre-comercial "Prueba" --correo contacto@ejemplo.com --telefono 042345678 --entorno sandbox ``` La API responde 200 OK con el perfil completo ya actualizado, con la misma forma que en [Leer el perfil](#respuesta). Sabrás que funcionó si los campos que enviaste aparecen con sus valores nuevos. ## Cambiar el logo ``` POST /v1/contribuyentes/{identificacion}/perfil/logo Content-Type: multipart/form-data ``` Sube la imagen como formulario `multipart/form-data` con un único campo de archivo llamado `logo`. El logo nuevo reemplaza al anterior. | Regla | Detalle | |---|---| | Nombre del campo | `logo` | | Formato | Imagen PNG o JPEG válida. El tipo de la parte del formulario debe ser exactamente `image/png` o `image/jpeg` y coincidir con el contenido. | | Tamaño | Mayor que 0 y hasta 512 KB (524.288 bytes). | | Dimensiones | Hasta 16.777.216 píxeles en total (ancho por alto). | | Cuerpo completo | Hasta 1 MiB incluyendo el formulario. | > [!NOTE] > Indica de forma explícita el tipo de la parte del formulario, como en los > ejemplos. La API valida el contenido y el tipo declarado, sin depender de la extensión del archivo. Si tu > cliente HTTP lo envía como `application/octet-stream`, responde 400. Los ejemplos suben el archivo `logo.png` de la carpeta actual. ```bash curl -s -X POST "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil/logo" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -F "logo=@logo.png;type=image/png" ``` ```csharp using System.Net.Http; using System.Net.Http.Headers; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var imagen = new ByteArrayContent(await File.ReadAllBytesAsync("logo.png")); imagen.Headers.ContentType = new MediaTypeHeaderValue("image/png"); using var formulario = new MultipartFormDataContent { { imagen, "logo", "logo.png" } }; using HttpResponseMessage respuesta = await http.PostAsync("/v1/contribuyentes/0123456789001/perfil/logo", formulario); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests with open("logo.png", "rb") as imagen: r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil/logo", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, files={"logo": ("logo.png", imagen, "image/png")}, timeout=60, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como logo.mjs y ejecuta: node logo.mjs import { readFile } from 'node:fs/promises'; const formulario = new FormData(); formulario.append('logo', new Blob([await readFile('logo.png')], { type: 'image/png' }), 'logo.png'); const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil/logo', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }, body: formulario }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], CURLOPT_POSTFIELDS => ['logo' => new CURLFile('logo.png', 'image/png', 'logo.png')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.io.ByteArrayOutputStream; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.util.UUID; // Dentro de: public static void main(String[] args) throws Exception String limite = UUID.randomUUID().toString(); ByteArrayOutputStream cuerpo = new ByteArrayOutputStream(); cuerpo.write(("--" + limite + "\r\n" + "Content-Disposition: form-data; name=\"logo\"; filename=\"logo.png\"\r\n" + "Content-Type: image/png\r\n\r\n").getBytes(StandardCharsets.UTF_8)); cuerpo.write(Files.readAllBytes(Path.of("logo.png"))); cuerpo.write(("\r\n--" + limite + "--\r\n").getBytes(StandardCharsets.UTF_8)); HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/perfil/logo")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .header("Content-Type", "multipart/form-data; boundary=" + limite) .POST(HttpRequest.BodyPublishers.ofByteArray(cuerpo.toByteArray())) .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); byte[] png = await File.ReadAllBytesAsync("logo.png"); PerfilEmisor perfil = await client.ActualizarLogoAsync("0123456789001", png, "image/png", "logo.png"); Console.WriteLine($"Logo vigente: {perfil.Logo}"); ``` ```javascript-sdk // Node.js 18 o superior. Guarda como logo-sdk.mjs y ejecuta: node logo-sdk.mjs import { readFile } from 'node:fs/promises'; import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const png = await readFile('logo.png'); const perfil = await client.actualizarLogo('0123456789001', png, 'image/png', 'logo.png'); console.log('Logo vigente:', perfil.logo); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) with open("logo.png", "rb") as archivo: perfil = client.actualizar_logo("0123456789001", archivo.read(), "image/png", "logo.png") print("Logo vigente:", perfil.logo) ``` ```php-sdk actualizarLogo('0123456789001', file_get_contents('logo.png'), 'image/png', 'logo.png'); echo 'Logo vigente: ' . $perfil->logo . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.PerfilEmisor; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); byte[] png = Files.readAllBytes(Path.of("logo.png")); PerfilEmisor perfil = client.actualizarLogo("0123456789001", png, "image/png", "logo.png"); System.out.println("Logo vigente: " + perfil.logo); ``` ```bash-cli # Resultado esperado: el mensaje "Logo actualizado." y el perfil con el campo logo lleno. ecuafact perfil-emisor logo logo.png --entorno sandbox ``` Puedes cambiar el logo con nuestros SDK de .NET, Node.js, Python, Java y PHP. Si usas otro lenguaje, usa los ejemplos HTTP o el CLI. La API responde 200 OK con el perfil completo, con la misma forma que en [Leer el perfil](#respuesta). Sabrás que funcionó si `logo` trae un valor. ## Estados de este endpoint Esta tabla reúne las respuestas de las tres operaciones del perfil. | `codEstado` | HTTP | Operación | Cuándo ocurre | Qué hacer | |---|---|---|---|---| | - | 200 | Todas | Se leyó o se actualizó el perfil. | Usa el perfil devuelto: ya refleja el cambio. | | 3003 (`solicitud_invalida`) | 400 | PUT | El JSON está mal formado, trae un campo no editable o algún valor incumple las longitudes o el formato indicado. | Envía solo los seis campos editables y corrige el campo indicado en `errores`. | | 3003 (`solicitud_invalida`) | 400 | POST logo | Falta el campo `logo`, el archivo está vacío, supera 512 KB o 16.777.216 píxeles, no se puede decodificar como imagen admitida o no coincide con el tipo declarado. `errores` trae el detalle. | Corrige el archivo o el tipo declarado y vuelve a subirlo. | | 3006 (`cuerpo_excedido`) | 413 | POST logo, PUT | El cuerpo completo supera 1 MiB. | Reduce el tamaño de la imagen. | | sin cuerpo | 415 | PUT, POST logo | El `Content-Type` no es `application/json` en el PUT ni `multipart/form-data` en el POST del logo. | Envía el `Content-Type` correcto. | | 3009 (`credenciales_invalidas`) | 401 | Todas | La API Key falta o no es válida. | Revisa la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | Todas | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. | | 3011 (`acceso_denegado`) | 403 | Todas | El contribuyente no está habilitado para tu API Key en este ambiente, o tu API Key está limitada y no incluye el scope `perfil:leer` (leer) ni `perfil:escribir` (actualizar y cambiar el logo). | Usa la `identificacion` de [`/v1/contexto`](/v1/guias/consulta-contexto). | | 3013 (`no_encontrado`) | 404 | Todas | No se encontró el perfil del emisor. | Contacta a soporte, porque el emisor no está configurado por completo. | | 5005 (`limite_solicitudes`) | 429 | Todas | Superaste el límite de solicitudes. | Espera los segundos que indica `Retry-After` y reintenta. | | 5003 (`error_dependencia`) | 502 | Todas | Ocurrió un error al leer el perfil o no se aceptó la actualización, por ejemplo por un valor con un formato que no se admite. | Revisa los valores enviados; si son correctos, reintenta en unos minutos. | | 5004 (`tiempo_agotado`) | 504 | Todas | No pudimos completar la operación a tiempo. | Reintenta en unos minutos; lee el perfil para confirmar si el cambio se aplicó. | | 5001 (`error_interno`) | 500 | PUT, POST logo | Ocurrió un error inesperado, por ejemplo una falla de comunicación al guardar. | Lee el perfil para ver si el cambio se aplicó; si no, reintenta. Si persiste, contacta a soporte con `X-Correlation-Id`. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Descargar PDF](/v1/guias/consulta-ride): comprueba cómo se ve el RIDE con los datos y el logo actualizados. - [Primeros pasos](/v1/guias/primeros-pasos): emite tu primer comprobante con el perfil listo. --- # Contexto Devuelve tu integración y los contribuyentes que puedes operar con tu API Key, junto con la identificación que usas en las rutas. Este endpoint te dice con quién puedes trabajar. Responde con el nombre de tu integración y la lista de [contribuyentes](/v1/guias/glosario) habilitados para tu API Key en el ambiente al que llamas, y para cada uno indica qué tipos de comprobante puede emitir y qué identificación debes usar en las demás rutas de la API. Te recomendamos hacerla como primera llamada de tu integración. Además de darte los datos que necesitas para emitir y consultar, te confirma que tu API Key funciona (y, en producción, que tu IP de salida está registrada), así que también puedes usarla como prueba de conexión cada vez que cambias de servidor o de credencial. ``` GET /v1/contexto X-Api-Key: ``` ## Cuándo usarlo Llámalo antes de emitir o consultar, porque el valor `identificacion` de cada contribuyente es el que va en las rutas `/v1/contribuyentes/{identificacion}/...`. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo registrarla, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). ## Parámetros Este endpoint no tiene parámetros de ruta ni de consulta; solo usa cabeceras. | Nombre | Tipo | Obligatorio | Descripción | |---|---|---|---| | `X-Api-Key` (cabecera) | string | Sí | Tu API Key. Ve [Autenticación](/v1/guias/autenticacion). | | `X-Api-Version` (cabecera) | string | No | Versión del contrato. Si no la envías, se usa la vigente. Ve [Versionado](/v1/guias/versionado). | ## Ejemplo > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Todos los ejemplos imprimen el estado HTTP y el cuerpo de la respuesta. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/contexto" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/contexto"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/contexto", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como contexto.mjs y ejecuta: node contexto.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contexto")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); Contexto contexto = await client.GetContextoAsync(); foreach (Contribuyente contribuyente in contexto.Contribuyentes ?? []) { Console.WriteLine($"{contribuyente.Identificacion} emite: {string.Join(",", contribuyente.TiposComprobante ?? [])}"); } ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) contexto = client.get_contexto() for contribuyente in contexto.contribuyentes or []: print(contribuyente.identificacion, contribuyente.tipos_comprobante) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como contexto-sdk.mjs y ejecuta: node contexto-sdk.mjs import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const contexto = await client.getContexto(); for (const contribuyente of contexto.contribuyentes ?? []) { console.log(contribuyente.identificacion, contribuyente.tiposComprobante); } ``` ```php-sdk getContexto(); foreach ($contexto->contribuyentes ?? [] as $contribuyente) { echo $contribuyente->identificacion . PHP_EOL; } ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.Contexto; import com.ecuafact.sdk.contracts.Contribuyente; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); Contexto contexto = client.getContexto(); for (Contribuyente contribuyente : contexto.contribuyentes()) { System.out.println(contribuyente.identificacion() + " " + contribuyente.tiposComprobante()); } ``` ```bash-cli # Resultado esperado: tu integración y sus contribuyentes habilitados, en tabla. ecuafact cuenta --entorno sandbox ``` Sabrás que funcionó si el estado es 200 y la lista `contribuyentes` trae al menos un contribuyente. ## Respuesta La API responde `200 OK` con este objeto JSON: ```json { "idCliente": "1f2e3d4c-5b6a-4789-9012-abcdef012345", "nombre": "Integracion de ejemplo", "contribuyentes": [ { "identificacion": "0123456789001", "puedeEmitir": true, "puedeRecibir": false, "tiposComprobante": [ "01", "03", "04", "05", "06", "07" ], "marcaBlanca": false } ] } ``` | Campo | Tipo | Descripción | |---|---|---| | `idCliente` | string (UUID) | Identificador de tu integración. Inclúyelo cuando pidas soporte. | | `nombre` | string | Nombre de tu integración. Si `contribuyentes` viene vacío, vale `Cliente API`. | | `contribuyentes` | array | Contribuyentes habilitados para tu API Key **en el ambiente de la URL** que llamaste. Viene vacío (`[]`) si aún no tienes ninguno habilitado en ese ambiente. | | `contribuyentes[].identificacion` | string | Identificación completa del contribuyente, tal como está registrada: su [RUC](/v1/guias/glosario) de 13 dígitos o una identificación de 5 a 13 dígitos. Es el valor que pones en `{identificacion}` en todas las rutas `/v1/contribuyentes/{identificacion}/...` y en `infoTributaria.ruc` al emitir. | | `contribuyentes[].puedeEmitir` | boolean | `true` si el contribuyente tiene al menos un tipo de comprobante habilitado para emitir. | | `contribuyentes[].puedeRecibir` | boolean | `true` si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión. | | `contribuyentes[].tiposComprobante` | array de string | Códigos de tipo de comprobante (`tipoDocumento`) que puede emitir, en orden: `01` factura, `03` liquidación de compra, `04` nota de crédito, `05` nota de débito, `06` guía de remisión y `07` comprobante de retención. Viene vacío si no puede emitir. | | `contribuyentes[].marcaBlanca` | boolean | `true` si el contribuyente es un emisor de marca blanca: sus comprobantes se emiten y se autorizan igual, pero no tienen RIDE. Para ese contribuyente, [Descargar PDF](/v1/guias/consulta-ride) responde 404 con el `codEstado` 3013 (`no_encontrado`); el [XML autorizado](/v1/guias/consulta-xml) se descarga igual. Lo configuramos nosotros por contribuyente; no lo cambias desde la API. | Si te habilitan un contribuyente o un tipo de comprobante, puede tardar un par de minutos en aparecer en esta respuesta. ## Estados de este endpoint | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La API devuelve el contexto. | Guarda la `identificacion` de cada contribuyente y úsala en las rutas. | | 3009 (`credenciales_invalidas`) | 401 | Falta la cabecera `X-Api-Key`, la API Key es inválida o está revocada. | Revisa la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). No reintentes sin cambiar nada. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** y revisa que tu proxy o balanceador no oculte la IP de salida. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto o de autenticaciones fallidas desde tu IP. | Espera los segundos que indica la cabecera `Retry-After` y reintenta. El detalle está en [Límite de request](/v1/guias/limite-de-request). | | 3007 (`version_no_soportada`) | 400 | Enviaste `X-Api-Version` con una versión que no existe. | Quita la cabecera o usa la versión vigente, `2026-11-16`. | | 5002 (`servicio_no_disponible`) | 503 | El servicio no está disponible temporalmente. | Espera lo que indica `Retry-After` y reintenta con una espera creciente. | Si un contribuyente que esperas no aparece en `contribuyentes`, todavía no está habilitado para tu integración en ese ambiente, y puedes solicitar su alta. El catálogo completo de códigos está en [Errores](/v1/guias/errores). ## Siguientes pasos - [Primeros pasos](/v1/guias/primeros-pasos): emite tu primer comprobante con la `identificacion` que acabas de obtener. - [Ambientes y contribuyentes](/v1/guias/ambientes): entiende por qué un contribuyente aparece en pruebas y no en producción. - [Seguimiento de una operación](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente): lista lo que ya emitió un contribuyente. --- # Seguimiento de una operación Consulta el resultado de una emisión: si sigue recibida, si el SRI la autorizó o la rechazó y cuál es su clave de acceso. Cuando emites un comprobante, la API lo recibe y responde de inmediato con un `idOperacion`, pero el resultado del [SRI](/v1/guias/glosario) llega después. Este endpoint te dice cómo está esa [operación](/v1/guias/glosario#operacion): si el comprobante sigue recibido y sin resultado, si el SRI lo autorizó o lo rechazó, si no se pudo emitir y por qué, y cuál es la [clave de acceso](/v1/guias/glosario#clave-de-acceso) que le asignamos. Puedes usarlo para seguir cada emisión hasta su estado final. Al terminar esta página sabrás leer el campo `estado`, junto con `codEstado`, `msgError` y `errores`, y qué hacer en cada caso: esperar, entregar el comprobante a tu cliente o corregirlo y emitirlo de nuevo. ``` GET /v1/operaciones/{idOperacion} X-Api-Key: ``` ## 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: ```text Implementa en este proyecto el seguimiento de una operación de Ecuafact hasta un estado final. 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/consulta-operacion.md antes de escribir código; no inventes campos. Reutiliza el SDK de Ecuafact que el proyecto ya use; si no usa ninguno, recomiéndame el SDK de su lenguaje o el CLI ecuafact, con una frase de motivo, y espera mi respuesta; HTTP directo solo si lo prefiero. Consulta GET /v1/operaciones/{idOperacion} con el idOperacion de la emisión (o usa urlEstado tal cual, que es una URL absoluta) y repite con espera creciente mientras el estado sea recibido (codEstado 1001 o 1002), con un tiempo máximo y sin saturar el límite de solicitudes; respeta Retry-After. Cualquier otro estado es final y se decide por estado y codEstado numérico: autorizado (2001) es el único con validez fiscal; en los demás casos lee errores como arreglo, explica la causa con el catálogo de la guía de errores y no reemitas ante 5001 ni 5007. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Prueba con una operación de pruebas que yo te indique o que emitas con un comprobante de prueba. Ejecuta el seguimiento e informa solo el estado final, el codEstado y la claveAcceso, y cualquier acción que yo deba hacer. ``` ## Cuándo usarlo La emisión responde `202 Accepted` con un `idOperacion`, y eso significa que el comprobante fue **recibido**, no que esté autorizado. Puedes enterarte del resultado de dos formas, y también combinarlas. - **Webhook**, la forma que te recomendamos. Te avisamos con `document.authorized`, `document.rejected` o `document.failed` en cuanto hay un resultado, así que no gastas solicitudes ni tienes que decidir cada cuánto preguntar. El detalle está en [Webhooks](/v1/guias/webhooks). - **Consulta**, con este endpoint. Te sirve si aún no tienes un servidor público para recibir webhooks, durante las pruebas, como respaldo cuando un webhook no llegó o para mostrar el estado cuando un usuario lo pide. Si emites muchos comprobantes, te recomendamos el webhook, porque consultar cada operación en bucle consume tu [límite de solicitudes](/v1/guias/limite-de-request), que por defecto es de 200 por minuto y de 60 en un sandbox. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). - [ ] El `idOperacion` que recibiste en la respuesta 202 de una [emisión](/v1/guias/emision). Debe ser de una emisión hecha con la misma API Key y en la misma URL, de pruebas o de producción. ## Parámetros | Nombre | Tipo | Obligatorio | Descripción | |---|---|---|---| | `idOperacion` (ruta) | string (UUID) | Sí | El `idOperacion` de la respuesta 202 de la emisión, que también viene en `urlEstado` y en la cabecera `Location`. Debe tener formato UUID, por ejemplo `3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f`. | | `X-Api-Key` (cabecera) | string | Sí | La misma API Key con la que emitiste. Una operación de otra integración responde 404. | El campo `urlEstado` de la respuesta de emisión trae la URL completa del seguimiento, por ejemplo `https://api-sandbox.mynexusapi.com/v1/operaciones/{idOperacion}`, y la cabecera `Location` trae el mismo valor. Puedes llamarla tal como viene, sin armar la ruta por tu cuenta. ## Ejemplo > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Reemplaza el `idOperacion` de ejemplo por el que recibiste al emitir. Todos los ejemplos imprimen el estado HTTP y el cuerpo de la respuesta. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como operacion.mjs y ejecuta: node operacion.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); Operation operacion = await client.GetOperacionAsync(Guid.Parse("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f")); Console.WriteLine($"{operacion.Estado} / {operacion.CodEstado} / {operacion.ClaveAcceso}"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) operacion = client.get_operacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f") print(operacion.estado, operacion.cod_estado, operacion.clave_acceso) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como operacion-sdk.mjs y ejecuta: node operacion-sdk.mjs import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const operacion = await client.getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'); console.log(operacion.estado, operacion.codEstado, operacion.claveAcceso); ``` ```php-sdk getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'); echo $operacion->estado . ' / ' . $operacion->codEstado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.Operation; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); Operation operacion = client.getOperacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"); System.out.println(operacion.estado() + " / " + operacion.codEstado()); ``` ```bash-cli # Resultado esperado: el estado, el codEstado y la claveAcceso de la operación. ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox ``` ## Respuesta La API responde `200 OK` con la operación en el primer nivel del JSON. La forma es la misma de la respuesta `202 Accepted` de la emisión, con los valores actuales. Este ejemplo corresponde a una factura ya autorizada: ```json { "estado": "autorizado", "codEstado": 2001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "001-001-000000123", "referenciaExterna": "FAC-ERP-4581", "claveAcceso": "0911202601179999999900110010010000001231234567810", "fhRecibido": "2026-11-09T10:15:00-05:00", "fhAutorizacion": "2026-11-09T10:15:18-05:00" } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | Resultado de la operación. Sus valores están en [Valores de estado](#valores-de-estado). | | `codEstado` | number | Código numérico de 4 dígitos que precisa el resultado. Su primer dígito coincide con el `estado`: 1 es `recibido`, 2 `autorizado`, 3 `rechazado`, 4 `rechazo_configuracion`, 5 `error` y 6 `cancelado`. Sus valores están en [Códigos de resultado](#codigos-de-resultado). | | `msgError` | string | Descripción general y fija del código, en español. Solo viene cuando el comprobante no se autorizó; con `recibido` o `autorizado` el campo no aparece. Muéstralo o regístralo, pero decide con `estado` y `codEstado`. | | `errores` | array de string | Detalle específico del resultado, por ejemplo el mensaje del SRI en un rechazo fiscal o la ruta del campo en un comprobante inválido. Viene siempre y es una lista vacía cuando no hay detalle. El texto es informativo, así que muéstralo o regístralo sin compararlo en tu código. | | `idOperacion` | string (UUID) | El identificador que consultaste. | | `urlEstado` | string | URL completa de este mismo seguimiento. | | `ambiente` | number | `1` para pruebas y `2` para producción. Siempre coincide con la URL que llamas. | | `tipoDocumento` | string | Tipo de comprobante: `01`, `03`, `04`, `05`, `06` o `07`. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, por ejemplo `001-001-000000123`. Si dejaste que te asignáramos el secuencial, aquí lo encuentras. | | `referenciaExterna` | string o `null` | La `referenciaExterna` que enviaste al emitir, o `null` si no la enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos que te asignamos. Vale `null` mientras el `codEstado` es 1001 y también cuando el comprobante no se llegó a emitir. Guárdala, porque la necesitas para descargar el RIDE y el XML. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con la zona horaria de Ecuador, por ejemplo `2026-11-09T10:15:00-05:00`. | | `fhAutorizacion` | string o `null` | Fecha y hora de autorización, en ISO 8601 con zona horaria. Puede ser `null` aunque el `estado` sea `autorizado`, porque la autorización no siempre trae fecha; por eso no la uses para decidir si el comprobante está autorizado. | Mientras el comprobante no tiene resultado, el `estado` es `recibido` y el `codEstado` vale 1001 si todavía no tiene clave de acceso o 1002 si ya la tiene. Tu sistema debe aceptar los dos valores y tratar la `claveAcceso` como opcional mientras el comprobante siga recibido: ```json { "estado": "recibido", "codEstado": 1002, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "001-001-000000123", "referenciaExterna": "FAC-ERP-4581", "claveAcceso": "0911202601179999999900110010010000001231234567810", "fhRecibido": "2026-11-09T10:15:00-05:00", "fhAutorizacion": null } ``` Así se ve, en cambio, un comprobante que el SRI rechazó. El `estado` es `rechazado`, el `codEstado` 3001 indica que el rechazo vino del SRI, `msgError` trae la descripción fija del código y `errores` trae el mensaje del SRI: ```json { "estado": "rechazado", "codEstado": 3001, "msgError": "El SRI rechazó el comprobante.", "errores": [ "CLAVE ACCESO REGISTRADA" ], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "001-001-000000123", "referenciaExterna": "FAC-ERP-4581", "claveAcceso": "0911202601179999999900110010010000001231234567810", "fhRecibido": "2026-11-09T10:15:00-05:00", "fhAutorizacion": null } ``` ### Valores de estado El campo `estado` tiene seis valores. Solo `recibido` es provisional; los demás son finales y ya no cambian. | Valor | Final | Significado | |---|---|---| | `recibido` | No | Recibimos el comprobante, pasó nuestras validaciones y todavía no tiene un resultado final. | | `autorizado` | Sí | El SRI autorizó el comprobante. Es el único valor con validez fiscal. | | `rechazado` | Sí | El comprobante no se autorizó por su contenido: lo rechazó el SRI o no cumplió una regla de la validación fiscal. `codEstado` dice cuál de los dos casos es. | | `rechazo_configuracion` | Sí | No se pudo emitir porque falta o está mal una configuración del emisor, como la firma electrónica, la suscripción o el cupo. | | `error` | Sí | No se pudo emitir por un fallo inesperado o porque algo impidió de forma definitiva que se autorice. | | `cancelado` | Sí | La plataforma canceló el envío de forma automática. El comprobante no se emitió y no consumió cupo. | No llames "autorizado" a un comprobante recibido, porque el 202 de la emisión solo indica que se **recibió**. Para uso fiscal solo cuenta que el `estado` sea `autorizado`. ### Códigos de resultado El `codEstado` precisa el resultado dentro de cada `estado`. Mientras el comprobante sigue `recibido` vale 1001 o 1002, y cuando el `estado` es final y distinto de `autorizado` dice la causa. La acción para cada código está en [Qué hacer según el estado](#que-hacer-segun-el-estado), y el catálogo completo, en [Errores](/v1/guias/errores#codigos-de-resultado-de-una-operacion). | `codEstado` | Nombre | `estado` | Significado | |---|---|---|---| | 1001 | `comprobante_recibido` | `recibido` | Recibimos el comprobante y todavía no tiene clave de acceso ni resultado. | | 1002 | `comprobante_enviado` | `recibido` | El comprobante ya tiene `claveAcceso` y espera el resultado del SRI. | | 2001 | `comprobante_autorizado` | `autorizado` | El SRI autorizó el comprobante. | | 3001 | `rechazo_sri` | `rechazado` | El SRI rechazó el comprobante. `errores` trae el mensaje del SRI. | | 3002 | `comprobante_invalido` | `rechazado` | La validación fiscal rechazó el contenido antes de enviarlo al SRI. `errores` trae el detalle por campo cuando existe. | | 4001 | `emisor_no_configurado` | `rechazo_configuracion` | Al emisor le falta configuración para emitir ante el SRI. | | 4002 | `firma_no_valida` | `rechazo_configuracion` | La firma electrónica del emisor está caducada o no es válida. | | 4003 | `suscripcion_inactiva` | `rechazo_configuracion` | La suscripción del emisor no está activa. | | 4004 | `cupo_agotado` | `rechazo_configuracion` | No quedan documentos en tus paquetes vigentes. | | 5001 | `error_interno` | `error` | Tuvimos un fallo inesperado y el comprobante no se completó. | | 5006 | `entrega_no_posible` | `error` | El comprobante no se pudo emitir y confirmamos que no se creó. | | 5007 | `resultado_no_confirmado` | `error` | No pudimos confirmar si el comprobante llegó a crearse. | | 6001 | `operacion_cancelada` | `cancelado` | La plataforma canceló el envío antes de emitirlo. | Los nombres de la tabla te sirven para leer la documentación y coinciden con las constantes de nuestros SDK, pero en el JSON solo viaja el número. Si recibes un `codEstado` que tu sistema no reconoce, decide por su primer dígito, que siempre coincide con el `estado`. Si es final, trátalo como un rechazo que debe revisar una persona y conserva el `idOperacion` para soporte. ## Qué hacer según el estado Una operación está en **estado final** cuando su `estado` es cualquier valor distinto de `recibido`. Mientras sea `recibido`, sigue esperando. | `estado` | `codEstado` | Final | Qué hacer | |---|---|---|---| | `recibido` | 1001 o 1002 | No | Espera el webhook o consulta más tarde, y no reenvíes la emisión. Con 1002 ya puedes guardar la `claveAcceso`, pero el comprobante todavía no está autorizado. | | `autorizado` | 2001 | Sí | Guarda la `claveAcceso`, descarga el [RIDE](/v1/guias/consulta-ride) y el [XML](/v1/guias/consulta-xml) y entrégalos a tu cliente. | | `rechazado` | 3001 | Sí | Es un rechazo fiscal y el cupo se consume. Corrige el comprobante según el mensaje del SRI que viene en `errores` y emítelo como un comprobante **nuevo**, con un secuencial nuevo (o sin `secuencial`, para que te asignemos el siguiente), una `Idempotency-Key` nueva y una `referenciaExterna` nueva. Si reutilizas el número rechazado, la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`). | | `rechazado` | 3002 | Sí | Corrige el dato que indica `errores` y reenvía el comprobante con claves nuevas. Puedes conservar el mismo número. | | `rechazo_configuracion` | 4001 | Sí | Revisa el RUC en **Cuenta > Contribuyentes** del Portal del Cliente: en el ambiente en que emitiste, la columna **Pruebas** o **Producción** debe mostrar **Listo** o **En producción**. Si muestra **Configurando**, espera a que termine; si ya está listo, escribe a soporte con el `idOperacion`. Después reenvía con el mismo número y claves nuevas. | | `rechazo_configuracion` | 4002 | Sí | En **Cuenta > Contribuyentes** del Portal del Cliente, pulsa **Reemplazar firma** en la fila del RUC y carga una firma electrónica vigente; si tu portal no muestra esa opción, cárgala en **Cuenta > Certificados** con **Reemplazar certificado**. Después reenvía con el mismo número y claves nuevas. | | `rechazo_configuracion` | 4003 | Sí | Regulariza la suscripción del emisor y reenvía con el mismo número y claves nuevas. | | `rechazo_configuracion` | 4004 | Sí | Compra un paquete de documentos y reenvía con el mismo número y claves nuevas. | | `error` | 5006 | Sí | El comprobante no se creó. Reenvíalo con el mismo número y claves nuevas. | | `error` | 5007 | Sí | **No reemitas**, porque el comprobante podría existir y lo duplicarías. Búscalo en el seguimiento y escribe a soporte con el `idOperacion`. | | `error` | 5001 | Sí | Escribe a soporte con el `idOperacion` antes de reemitir, para confirmar que el comprobante no existe. | | `cancelado` | 6001 | Sí | El comprobante no se emitió y no consumió cupo. Emítelo de nuevo con claves nuevas; puedes usar el mismo número. Con la misma `Idempotency-Key` recibirías otra vez esta operación cancelada. | En esta tabla, "claves nuevas" significa una `Idempotency-Key` nueva y una `referenciaExterna` nueva. Para conservar el número, envía el mismo `estab`, `ptoEmi` y `secuencial`. Si dejaste que te asignáramos el secuencial, lo encuentras en el `numeroDocumento` de esta misma respuesta o en el [listado de operaciones](#listado-de-operaciones-por-contribuyente). Un reenvío con el mismo número puede responder con el mismo `idOperacion` y no descuenta otro documento de tu cupo. > [!WARNING] > No reemplaces la `Idempotency-Key` ni la `referenciaExterna` mientras la > operación siga en `recibido`. Emitir de nuevo con datos de idempotencia > distintos crea un segundo comprobante. Un rechazo y una espera se manejan de forma distinta. Un **rechazo** (`rechazado` o `rechazo_configuracion`) exige corregir el comprobante o la configuración del emisor antes de emitir de nuevo. Una **espera** (`recibido`) no requiere ninguna acción: consulta más tarde o espera el webhook. ## Listado de operaciones por contribuyente Para reconciliar lo emitido en un período, usa el listado paginado por contribuyente. No devuelve todo el historial de la cuenta: exige la `identificacion` y limita el rango de fechas a 366 días. No consume cupo. ```text GET /v1/operaciones?identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50 X-Api-Key: ``` | Nombre | Tipo | Obligatorio | Descripción | |---|---|---|---| | `identificacion` (consulta) | string | Sí | La identificación completa que devuelve `GET /v1/contexto`, la misma de `infoTributaria.ruc`. | | `desde` (consulta) | string (`yyyy-MM-dd`) | No | Fecha inicial, desde el 2000-01-01. Si no la envías, se usan los 30 días anteriores a `hasta`. | | `hasta` (consulta) | string (`yyyy-MM-dd`) | No | Fecha final. Si no la envías, se usa la fecha de hoy. Entre `desde` y `hasta` puede haber como máximo 366 días. | | `tipoDocumento` (consulta) | string | No | `01`, `03`, `04`, `05`, `06` o `07`. Sin él, devuelve todos los tipos. | | `buscar` (consulta) | string | No | Texto libre de hasta 100 caracteres, sin caracteres de control, para filtrar por número, clave, contraparte o referencia. | | `pagina` (consulta) | number | No | Página, de 1 a 10000. Por defecto 1. | | `tamanoPagina` (consulta) | number | No | Filas por página, de 1 a 100. Por defecto 20. | | `X-Api-Key` (cabecera) | string | Sí | Tu API Key. | Los ejemplos listan las facturas de los primeros 10 días de noviembre de 2026 del contribuyente de pruebas. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones?identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); string consulta = "identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50"; using HttpResponseMessage respuesta = await http.GetAsync("/v1/operaciones?" + consulta); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```javascript // Node.js 18 o superior. Guarda como listado.mjs y ejecuta: node listado.mjs const consulta = new URLSearchParams({ identificacion: '0123456789001', desde: '2026-11-01', hasta: '2026-11-10', tipoDocumento: '01', pagina: '1', tamanoPagina: '50' }); const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones?${consulta}`, { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php '0123456789001', 'desde' => '2026-11-01', 'hasta' => '2026-11-10', 'tipoDocumento' => '01', 'pagina' => 1, 'tamanoPagina' => 50, ]); $ch = curl_init('https://api-sandbox.mynexusapi.com/v1/operaciones?' . $consulta); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` La respuesta es una página de comprobantes: ```json { "comprobantes": [ { "claveAcceso": "1011202601099215640600110010010000000025469774111", "numeroDocumento": "001-001-000000002", "tipoDocumento": "01", "fechaEmision": "10/11/2026", "identificacionContraparte": "0123456789", "razonSocialContraparte": "CONTRIBUYENTE DE PRUEBAS", "total": 1.00, "estado": "recibido", "codEstado": 1002, "errores": [], "fhAutorizacion": null } ], "pagina": 1, "tamanoPagina": 50, "hayMas": false } ``` | Campo | Tipo | Descripción | |---|---|---| | `comprobantes` | array | Comprobantes de la página; vacío si no hay ninguno en el período. | | `comprobantes[].claveAcceso` | string | Clave de acceso de 49 dígitos. | | `comprobantes[].numeroDocumento` | string | Número con la forma `estab-ptoEmi-secuencial`. | | `comprobantes[].tipoDocumento` | string | Tipo de comprobante: `01`, `03`, `04`, `05`, `06` o `07`. | | `comprobantes[].fechaEmision` | string | Fecha de emisión con formato `dd/MM/yyyy`. | | `comprobantes[].identificacionContraparte` | string | Identificación del comprador, del proveedor o del destinatario. | | `comprobantes[].razonSocialContraparte` | string | Razón social de la contraparte. | | `comprobantes[].total` | number | Importe total del comprobante. | | `comprobantes[].estado` | string | Mismo significado que en [Valores de estado](#valores-de-estado). | | `comprobantes[].codEstado` | number | Mismo significado que en [Códigos de resultado](#codigos-de-resultado). | | `comprobantes[].msgError` | string | Descripción fija del código. Solo viene cuando el comprobante no se autorizó. | | `comprobantes[].errores` | array de string | Detalle del resultado; lista vacía cuando no hay detalle. | | `comprobantes[].fhAutorizacion` | string o `null` | Fecha y hora de autorización en ISO 8601; `null` si no está autorizado. | | `pagina` | number | Página devuelta. | | `tamanoPagina` | number | Filas por página usadas en la consulta. | | `hayMas` | boolean | `true` si existe una página siguiente. | Tu API Key debe tener el scope `comprobantes:leer` y acceso al contribuyente consultado. Si no lo tiene, la API responde 403 con el `codEstado` 3011 (`acceso_denegado`); un filtro fuera de rango, por ejemplo un período mayor de 366 días, responde 400 con el `codEstado` 3012 (`filtros_invalidos`). Para un volumen grande, recorre las páginas con `hayMas` en lugar de pedir todo en una sola llamada. Los estados de este listado están en [Estados de este endpoint](#estados-de-este-endpoint). ### Listado desde el CLI El comando `ecuafact operaciones listar` hace esta misma consulta. Si no indicas `--identificacion`, toma el contribuyente de `GET /v1/contexto` cuando hay uno solo; si la integración tiene varios, se detiene y te pide `--identificacion`, sin elegir uno en silencio. `--json` y `--csv` equivalen a `--salida json` y `--salida csv`. La tabla muestra el número, el tipo, la fecha, el estado, el `codEstado`, el total, la identificación de la contraparte y la clave de acceso; en JSON recibes la página completa, con `pagina`, `tamanoPagina` y `hayMas`. ```bash-cli # Resultado esperado: una fila por comprobante, con su estado y codEstado. ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --tipo 01 --entorno sandbox # La pagina completa en JSON, para guardarla o procesarla. ecuafact operaciones listar --identificacion 0123456789001 --desde 2026-11-01 --hasta 2026-11-10 --json # Un CSV para abrir en Excel. ecuafact operaciones listar --identificacion 0123456789001 --desde 2026-11-01 --hasta 2026-11-10 --csv > emitidos.csv ``` Si la respuesta trae `hayMas` en `true`, repite el comando con `--pagina` una unidad mayor. El comando te recuerda la página siguiente en el mensaje de resumen. ### Listado en Postman En la colección, abre **03 · Listado de operaciones > 03.1 Listar operaciones**. Usa las variables del environment `baseUrl`, `apiKey` e `identificacion`, y ajusta `desde` y `hasta` al período que quieras conciliar. La petición trae ejemplos de `200` con una página de comprobantes, de `403` con el `codEstado` 3011 y de `400` con el 3012. ## Seguimiento con espera Si no usas webhooks, puedes consultar la operación cada pocos segundos hasta llegar a un estado final, siempre con un tope de tiempo. El resultado del SRI puede tardar varios minutos, y consultar más seguido que cada 5 segundos no lo acelera. Este ejemplo consulta cada 10 segundos durante un máximo de 10 minutos. Si llega al tope sin un estado final, no es un error. Deja el comprobante como pendiente en tu sistema y vuelve a consultarlo más tarde, o espera el webhook. ```bash # Requiere jq. Uso: ./seguir.sh 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f ID="$1" for intento in $(seq 1 60); do CUERPO=$(curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/$ID" -H "X-Api-Key: $ECUAFACT_API_KEY") ESTADO=$(echo "$CUERPO" | jq -r '.estado') echo "Intento $intento: $ESTADO" if [ "$ESTADO" != "recibido" ]; then echo "$CUERPO"; exit 0; fi sleep 10 done echo "Sin estado final tras 10 minutos: consulta mas tarde." ``` ```csharp using System.Net.Http; using System.Text.Json; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); string idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; DateTime limite = DateTime.UtcNow.AddMinutes(10); while (DateTime.UtcNow < limite) { using HttpResponseMessage respuesta = await http.GetAsync($"/v1/operaciones/{idOperacion}"); string cuerpo = await respuesta.Content.ReadAsStringAsync(); if (!respuesta.IsSuccessStatusCode) { Console.WriteLine($"{(int)respuesta.StatusCode} {cuerpo}"); return; } using JsonDocument json = JsonDocument.Parse(cuerpo); string estado = json.RootElement.GetProperty("estado").GetString()!; Console.WriteLine(estado); if (estado != "recibido") { Console.WriteLine(cuerpo); return; } await Task.Delay(TimeSpan.FromSeconds(10)); } Console.WriteLine("Sin estado final tras 10 minutos: consulta mas tarde."); ``` ```python import os import time import requests id_operacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" url = f"https://api-sandbox.mynexusapi.com/v1/operaciones/{id_operacion}" headers = {"X-Api-Key": os.environ["ECUAFACT_API_KEY"]} limite = time.monotonic() + 600 while time.monotonic() < limite: r = requests.get(url, headers=headers, timeout=30) if r.status_code != 200: print(r.status_code, r.text) break operacion = r.json() print(operacion["estado"], "/", operacion["codEstado"]) if operacion["estado"] != "recibido": print(r.text) break time.sleep(10) else: print("Sin estado final tras 10 minutos: consulta mas tarde.") ``` ```javascript // Node.js 18 o superior. Guarda como seguir.mjs y ejecuta: node seguir.mjs const idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'; const limite = Date.now() + 10 * 60 * 1000; const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms)); let terminado = false; while (!terminado && Date.now() < limite) { const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones/${idOperacion}`, { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); if (res.status !== 200) { console.log(res.status, await res.text()); break; } const operacion = await res.json(); console.log(operacion.estado, '/', operacion.codEstado); terminado = operacion.estado !== 'recibido'; if (terminado) { console.log(JSON.stringify(operacion)); } else { await esperar(10000); } } if (!terminado) { console.log('Sin estado final: consulta mas tarde.'); } ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($estado !== 200) { echo $estado . ' ' . $cuerpo . PHP_EOL; break; } $operacion = json_decode($cuerpo, true); echo $operacion['estado'] . ' / ' . $operacion['codEstado'] . PHP_EOL; $terminado = $operacion['estado'] !== 'recibido'; if ($terminado) { echo $cuerpo . PHP_EOL; } else { sleep(10); } } if (!$terminado) { echo 'Sin estado final: consulta mas tarde.' . PHP_EOL; } ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.regex.Matcher; import java.util.regex.Pattern; // Dentro de: public static void main(String[] args) throws Exception String idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/operaciones/" + idOperacion)) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); Pattern patronEstado = Pattern.compile("\"estado\"\\s*:\\s*\"([a-z_]+)\""); long limite = System.currentTimeMillis() + 10 * 60 * 1000; boolean terminado = false; while (!terminado && System.currentTimeMillis() < limite) { HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); if (respuesta.statusCode() != 200) { System.out.println(respuesta.statusCode() + " " + respuesta.body()); break; } Matcher estado = patronEstado.matcher(respuesta.body()); String valorEstado = estado.find() ? estado.group(1) : ""; System.out.println(valorEstado); terminado = !valorEstado.isEmpty() && !valorEstado.equals("recibido"); if (terminado) { System.out.println(respuesta.body()); } else { Thread.sleep(10_000); } } if (!terminado) { System.out.println("Sin estado final: consulta mas tarde."); } ``` Sabrás que funcionó si el bucle termina con el `estado` en `autorizado` y te muestra la `claveAcceso`. En pruebas, eso ocurre cuando emitiste un comprobante válido. ## Estados de este endpoint Cuando la consulta falla, el cuerpo trae la forma de error de toda la API, con `estado`, `codEstado`, `msgError` y `errores`, que se explica en [Errores](/v1/guias/errores#forma-del-error). | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La API encontró la operación. | Lee el `estado` y el `codEstado` como se explica en [Qué hacer según el estado](#que-hacer-segun-el-estado). | | 3013 (`no_encontrado`) | 404 | No existe una operación con ese `idOperacion` para tu integración, porque el valor está mal copiado, pertenece a otra integración o se emitió en el otro ambiente. | Revisa el `idOperacion` y confirma que llamas a la misma URL, de pruebas o de producción, donde emitiste. | | 3013 (`no_encontrado`) | 404 | El `idOperacion` de la ruta no tiene formato UUID. | Copia el `idOperacion` tal como vino en la respuesta 202. | | 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes. | Espera lo que indica `Retry-After`, consulta con menos frecuencia o usa webhooks. | | 5002 (`servicio_no_disponible`) | 503 | El servicio no está disponible temporalmente. | Reintenta con una espera creciente. | Para el listado de operaciones, los estados propios son estos, además de los de autenticación y límite de la tabla anterior: | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La API devuelve la página de comprobantes, que puede venir vacía. | Si `hayMas` es `true`, pide la página siguiente. | | 3003 (`solicitud_invalida`) | 400 | Falta `identificacion` o una fecha no tiene el formato `yyyy-MM-dd`. | Envía `identificacion` y fechas con formato `2026-11-01`. | | 3012 (`filtros_invalidos`) | 400 | Un filtro está fuera de rango: fecha anterior al 2000-01-01, `hasta` menor que `desde`, más de 366 días entre ambas, `pagina` fuera de 1 a 10000, `tamanoPagina` fuera de 1 a 100, `buscar` de más de 100 caracteres o `tipoDocumento` distinto de `01`, `03`, `04`, `05`, `06` o `07`. | Corrige el filtro que indica `errores` y repite la consulta. | | 3002 (`comprobante_invalido`) | 422 | La `identificacion` no tiene entre 5 y 13 dígitos numéricos. | Usa la `identificacion` que devuelve `GET /v1/contexto`. | | 3011 (`acceso_denegado`) | 403 | La `identificacion` no es de un contribuyente habilitado para tu API Key en este ambiente, o no puede emitir el `tipoDocumento` que pediste. | Revisa `GET /v1/contexto` y usa un contribuyente y un tipo habilitados. | El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar en bucle. - [Descargar PDF](/v1/guias/consulta-ride): obtén el RIDE cuando el comprobante esté `autorizado`. - [Buenas prácticas](/v1/guias/buenas-practicas): reintentos e idempotencia sin duplicar comprobantes. --- # Consumo y cuotas Devuelve cuántos documentos te quedan para emitir en el ambiente de la URL que llamas, sumando tus paquetes vigentes. Cada comprobante que envías descuenta un documento de tu cupo, que es la suma de tus paquetes de documentos pagados y vigentes en ese ambiente. Con `GET /v1/consumo` puedes saber cuántos documentos tienes en paquetes, cuántos están reservados por emisiones que aún esperan resultado, cuántos ya se consumieron, cuántos te quedan y cuándo vence el próximo paquete. En esta página verás cómo consultarlo, qué significa cada campo de la respuesta con un ejemplo numérico, y en qué momento de una emisión se reserva, se consume o se libera un documento. ``` GET /v1/consumo X-Api-Key: ``` ## Cuándo usarlo Te recomendamos consultarlo antes de enviar un lote grande de comprobantes, para no quedarte sin [cupo](/v1/guias/glosario) a mitad del lote. También puedes usarlo desde un tablero o una alerta interna que avise cuando queden pocos documentos. Es el mismo saldo que ves en el Portal del Cliente, y cada ambiente tiene su propio cupo. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`, como se explica en [Autenticación](/v1/guias/autenticacion). Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración, como se explica en [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). El sandbox acepta cualquier IP. - [ ] Un paquete de documentos pagado y vigente en el ambiente de la URL que llamas. El [sandbox](/v1/guias/sandbox) ya incluye un paquete de pruebas. ## Parámetros Este endpoint no tiene parámetros de ruta ni de consulta; solo necesita tu API Key. | Nombre | Tipo | Obligatorio | Descripción | |---|---|---|---| | `X-Api-Key` (cabecera) | string | Sí | Tu API Key. | ## Ejemplo Los ejemplos consultan el cupo de tu integración en el ambiente de pruebas e imprimen la respuesta. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/consumo" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/consumo"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/consumo", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como consumo.mjs y ejecuta: node consumo.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consumo', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/consumo")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using var client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); QuotaBucket cupo = await client.GetConsumoAsync(); Console.WriteLine($"Disponibles {cupo.Disponibles} de {cupo.LimiteDocumentos}; próximo vencimiento {cupo.VigenteHasta:yyyy-MM-dd}"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) cupo = client.get_consumo() print("Disponibles", cupo.disponibles, "de", cupo.limite_documentos, "- próximo vencimiento", cupo.vigente_hasta) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como consumo-sdk.mjs y ejecuta: node consumo-sdk.mjs import { EcuafactClient } from '@ecuafact/sdk'; const client = new EcuafactClient({ baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: process.env.ECUAFACT_API_KEY }); const cupo = await client.getConsumo(); console.log('Disponibles', cupo.disponibles, 'de', cupo.limiteDocumentos, '- próximo vencimiento', cupo.vigenteHasta); ``` ```php-sdk getConsumo(); echo 'Disponibles ' . $cupo->disponibles . ' de ' . $cupo->limiteDocumentos . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.QuotaBucket; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); QuotaBucket cupo = client.getConsumo(); System.out.println("Disponibles " + cupo.disponibles() + " de " + cupo.limiteDocumentos()); ``` ```bash-cli # Resultado esperado: límite, reservados, consumidos y disponibles, en tabla. ecuafact consumo --entorno sandbox ``` ## Respuesta La API responde `200 OK` con este objeto JSON: ```json { "limiteDocumentos": 1500, "reservados": 5, "consumidos": 990, "disponibles": 505, "vigenteHasta": "2027-03-01T00:00:00Z", "limiteExtra": 0, "reservadosExtra": 0, "consumidosExtra": 0, "disponiblesExtra": 0 } ``` Los cuatro primeros campos suman todos tus paquetes pagados y vigentes del ambiente. Un paquete vencido, sin pagar o anulado no cuenta. | Campo | Tipo | Descripción | |---|---|---| | `limiteDocumentos` | number | Documentos de todos tus paquetes vigentes. | | `reservados` | number | Documentos apartados por emisiones recibidas que aún no tienen resultado final. | | `consumidos` | number | Documentos ya descontados: emisiones con resultado final (autorizadas, rechazadas o con rechazo de configuración), intentos con 422 y reenvíos con cambios. | | `disponibles` | number | Documentos que aún puedes emitir: `limiteDocumentos - reservados - consumidos`. | | `vigenteHasta` | string | Fecha y hora, en UTC e ISO 8601, en que vence el próximo paquete con saldo. `9999-12-31T00:00:00Z` significa que tus paquetes con saldo no vencen, como el paquete de pruebas. | | `limiteExtra`, `reservadosExtra`, `consumidosExtra`, `disponiblesExtra` | number | Se mantienen por compatibilidad y valen 0: todo el saldo está en los cuatro primeros campos. | ## Paquetes Cada paquete es de un ambiente, tiene una cantidad de documentos y una vigencia: - **Producción.** Dura un año desde el pago. Lo compras en **Consumo**, con **Comprar documentos**, en el Portal del Cliente; con transferencia o depósito, el paquete se activa cuando se confirma el pago. El precio se muestra sin IVA y el IVA se suma al pagar. - **Pruebas.** El [sandbox](/v1/guias/sandbox) incluye 3.000 documentos que no vencen. Al emitir, el documento se descuenta del paquete vigente que vence primero; los paquetes sin vencimiento se usan al final. El saldo de un paquete vencido se pierde. ## Ejemplo numérico Supón que en producción tienes un paquete de 1.000 documentos que vence el 1 de marzo de 2027 y otro de 500 que vence el 1 de junio de 2027. Así cambian los valores a medida que emites: 1. **Al inicio** no has emitido nada, así que `limiteDocumentos` vale 1500, `reservados` 0, `consumidos` 0, `disponibles` 1500 y `vigenteHasta` es el 1 de marzo de 2027. 2. **Emites 995 comprobantes.** Cada emisión aceptada con un 202 aparta 1 documento del paquete que vence primero. Cuando 990 ya tienen resultado del SRI y 5 siguen esperando, `reservados` vale 5, `consumidos` 990 y `disponibles` 505. Es la respuesta de ejemplo de arriba. 3. **Llegan los 5 resultados pendientes**, que pasan de reservados a consumidos: `reservados` vale 0, `consumidos` 995 y `disponibles` 505. 4. **Emites 10 más.** Los 5 primeros salen del primer paquete, al que le quedaban 5, y los 5 siguientes, del segundo. El primer paquete queda sin saldo, así que `vigenteHasta` pasa al 1 de junio de 2027. 5. **Una de esas 10 operaciones queda `cancelado`.** Su documento se libera y vuelve a estar disponible, así que `disponibles` sube 1. ## Cuándo se reserva, consume o libera La tabla muestra el efecto de cada momento de una emisión sobre el cupo: | Momento | Efecto en el cupo | |---|---| | La emisión se rechaza por acceso (401 o 403), por cupo (429) o por una solicitud mal formada (400) | Ninguno. | | La emisión se rechaza con 422 por formato o validación del comprobante | Consume 1 como intento, aunque no se emita nada. Repetir la misma `Idempotency-Key` con el mismo cuerpo devuelve el mismo 422 sin consumir otro. | | Validas con `/validar` | Ninguno. | | La emisión se acepta con un 202 y `estado` en `recibido` | Aparta 1: `reservados` sube 1 y `disponibles` baja 1. | | Llega un reintento idempotente (misma `Idempotency-Key` y mismo cuerpo), que responde con el mismo `idOperacion` y el estado actual de la operación | Ninguno, porque es la misma operación. | | La operación termina en `autorizado` o en `rechazado` con el `codEstado` 3001 (`rechazo_sri`) | Consume: `reservados` baja 1 y `consumidos` sube 1. Un rechazo del SRI también consume, porque el comprobante sí llegó al SRI. | | La operación termina en `rechazado` con 3002 (`comprobante_invalido`) o en `rechazo_configuracion` | Consume: `reservados` baja 1 y `consumidos` sube 1. | | Reenvías un comprobante rechazado con el mismo número y el mismo contenido | Ninguno, aunque hayas cambiado la firma electrónica o la modalidad del contribuyente. | | Reenvías un comprobante rechazado con el mismo número y otro contenido (por ejemplo, otro comprador) | Consume 1: es otro envío. Sin saldo, el reenvío responde 429. | | El contribuyente no tiene firma electrónica configurada | Ninguno: la emisión se rechaza sin consumir. | | La operación termina en `error` con 5006 (`entrega_no_posible`) o 5007 (`resultado_no_confirmado`) | Sigue reservado: `reservados` y `disponibles` no cambian. Si reenvías el mismo número, el reenvío usa ese mismo documento y no reserva otro; el documento se consume cuando el reenvío obtiene su resultado. | | La operación termina en `error` con 5001 (`error_interno`) | Según el caso, el documento queda consumido o sigue reservado. Al revisar la operación, soporte te confirma cómo quedó. | | La operación termina en `cancelado` | Libera: `reservados` baja 1 y `disponibles` sube 1. Es el único caso que devuelve el documento. | Cada comprobante descuenta un solo documento, aunque lo consultes, lo descargues o lo reenvíes por correo muchas veces. Las consultas, incluidas las del SRI, no consumen cupo. > [!WARNING] > Sin un paquete vigente con saldo, la emisión responde 429 con el `codEstado` > 4004 (`cupo_agotado`). Compra un paquete antes de enviar lotes grandes. ## Estados de este endpoint | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La API devuelve el cupo. | Compara `disponibles` con el tamaño de tu próximo lote. | | 3013 (`no_encontrado`) | 404 | Tu integración no tiene paquetes en este ambiente. | Compra un paquete para ese ambiente o, en pruebas, crea un [sandbox](/v1/guias/sandbox). | | 3009 (`credenciales_invalidas`) | 401 | La API Key falta o es inválida. | Revisa la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes. | Espera lo que indica `Retry-After` y reintenta. | | 5002 (`servicio_no_disponible`) | 503 | Nuestro servicio no está disponible por un momento. | Reintenta con espera creciente. | El 429 con el `codEstado` 4004 (`cupo_agotado`), que indica cupo agotado, lo devuelve la emisión y no esta consulta. El catálogo completo está en [Errores](/v1/guias/errores). ## Siguientes pasos - [Límite de request](/v1/guias/limite-de-request): no confundas el cupo de documentos con el límite de solicitudes por minuto. - [Seguimiento de una operación](/v1/guias/consulta-operacion): revisa qué operaciones siguen reservando cupo. - [Buenas prácticas](/v1/guias/buenas-practicas#cupo): planifica lotes grandes sin quedarte sin cupo. --- # Contribuyente por identificación Consulta en el catastro del SRI los datos de un contribuyente a partir de su cédula, RUC o pasaporte. Con este endpoint puedes buscar a un [contribuyente](/v1/guias/glosario) en el catastro público del [SRI](/v1/guias/glosario) por su cédula, RUC o pasaporte, y obtener su razón social, su estado, su régimen tributario, sus establecimientos y otros datos registrados. Te sirve para llenar los datos de un comprador o un proveedor sin errores de tipeo, o para revisar su situación antes de emitirle un comprobante. Al terminar esta página sabrás qué datos devuelve la consulta y cómo tolerar los que vienen vacíos. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas. > La consulta lee el catastro público del SRI en ambos ambientes, así que los > datos que devuelve son los reales del catastro. ## Endpoint ``` GET /v1/consultas/contribuyentes/{identificacion} X-Api-Key: ``` | Cabecera | Obligatoria | Descripción | |---|---|---| | `X-Api-Key` | Sí | Tu [API Key](/v1/guias/glosario). | | `X-Api-Version` | No | Versión del contrato. Si la omites, se usa la vigente. | La respuesta es un objeto JSON con los campos en el primer nivel. Esta consulta **no consume cupo** de documentos, pero sí cuenta para el límite de solicitudes por minuto de tu API Key, que se explica en [Límites](/v1/guias/limites). ## Cuándo usarlo - **Autocompletar al comprador al facturar.** Tu usuario escribe la cédula o el RUC del cliente y tu sistema llena `razonSocialComprador` con `razonSocial`, o con `nombreCompleto` si la razón social no viene. - **Revisar a un proveedor antes de emitir una retención o una liquidación de compra.** Comprueba que `estado` sea `ACTIVO` y lee `agenteRetencion`, `contribuyenteEspecial` y `obligadoLlevarContabilidad`, que tu área contable usa para decidir los porcentajes. - **Mantener actualizada tu ficha de clientes y proveedores**, con las direcciones de sus [establecimientos](/v1/guias/glosario), sus representantes legales y su fecha de cese. Si solo necesitas saber si el número está bien escrito, es decir, si su dígito verificador es correcto, puedes usar [Validar identificación](/v1/guias/consulta-identificacion). Esa consulta no depende del SRI y te responde más rápido. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). - [ ] Para ver datos reales, una cédula o un RUC que exista en el catastro del SRI, por ejemplo el RUC de tu empresa. ## Parámetros | Nombre | Dónde | Tipo | Obligatorio | Descripción | |---|---|---|---|---| | `identificacion` | ruta | string | Sí | Cédula de 10 dígitos, RUC de 13 dígitos o pasaporte. La API elimina los espacios al inicio y al final. | | `fusionar` | consulta | boolean | No | Con `true`, el valor por defecto, combina los datos de todas las fuentes disponibles. Con `false` devuelve los datos de la primera fuente que responda, lo que es más rápido pero puede traer menos campos. Solo acepta `true` o `false`; con otro valor la API responde 400 con el `codEstado` 3003 (`solicitud_invalida`). | | `fuente` | consulta | string | No | `Todas`, el valor por defecto, o `SriCatastro` para consultar solo el catastro del SRI. No distingue mayúsculas. Con otro valor la API responde 400 con el `codEstado` 3012 (`filtros_invalidos`). | ## Ejemplo El RUC `0123456789001` es el identificador de prueba de esta documentación y **no existe en el catastro**; para ver datos reales, reemplázalo por el RUC de tu propia empresa. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001?fusionar=true" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/consultas/contribuyentes/0123456789001?fusionar=true"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, params={"fusionar": "true"}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001?fusionar=true', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001?fusionar=true")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); ContribuyenteConsulta contribuyente = await client.ConsultarContribuyenteAsync("0123456789001", fusionar: true); Console.WriteLine(contribuyente.RazonSocial + " " + contribuyente.Estado); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) contribuyente = client.consultar_contribuyente("0123456789001", fusionar=True) print(contribuyente.razon_social, contribuyente.estado) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const contribuyente = await client.consultarContribuyente("0123456789001", true); console.log(contribuyente.razonSocial, contribuyente.estado); ``` ```php-sdk consultarContribuyente('0123456789001', true); echo $contribuyente->razonSocial . ' ' . $contribuyente->estado . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.ContribuyenteConsulta; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); ContribuyenteConsulta contribuyente = client.consultarContribuyente("0123456789001", true, null); System.out.println(contribuyente.razonSocial() + " " + contribuyente.estado()); ``` ```bash-cli # Resultado esperado: con un RUC que existe en el catastro, sus datos en tabla. # Con el RUC de prueba 0123456789001, un error 404 con el `codEstado` 3013 (`no_encontrado`). ecuafact ruc consultar 0123456789001 --entorno sandbox ``` Con un RUC que existe en el catastro, el resultado esperado es un 200 con el objeto que se describe en la sección siguiente. Con `0123456789001` recibes un 404 con el `codEstado` 3013 (`no_encontrado`) y el mensaje "Recurso no encontrado.". ## Respuesta La API responde `200 OK`. Los valores de este ejemplo son ilustrativos, porque los reales dependen de lo que devuelva el catastro del SRI en el momento de la consulta. ```json { "identificacion": "0123456789001", "tipoIdentificacion": "RucPersonaNatural", "nombreCompleto": "CONTRIBUYENTE DE PRUEBA", "razonSocial": "CONTRIBUYENTE DE PRUEBA", "nombreComercial": "COMERCIAL DE PRUEBA", "clase": "PersonaNatural", "estado": "ACTIVO", "regimen": "GENERAL", "actividadEconomicaPrincipal": "VENTA AL POR MENOR DE ARTICULOS DE OFICINA", "obligadoLlevarContabilidad": false, "agenteRetencion": false, "contribuyenteEspecial": false, "fechaInicioActividades": "2015-03-02T00:00:00", "fechaCese": null, "fechaReinicioActividades": null, "fechaActualizacion": "2026-01-15T00:00:00", "representantesLegales": [], "establecimientos": [ { "numero": "001", "nombreComercial": "COMERCIAL DE PRUEBA", "tipo": "MATRIZ", "direccionCompleta": "AV. DE PRUEBA 123 Y CALLE FICTICIA", "estado": "ABIERTO", "esMatriz": true } ], "estadoTributario": { "tieneDeuda": false, "tieneImpugnacion": false, "tieneRemision": false, "resumenDeuda": null, "resumenImpugnacion": null, "resumenRemision": null, "consultadoEn": "2026-10-07T08:00:00" }, "fuenteOrigen": "SriCatastro", "consultadoEn": "2026-10-07T08:00:00" } ``` Cualquier campo puede venir `null` cuando la fuente no tiene el dato, así que programa tu integración para tolerarlo. Por ejemplo, `nombreComercial` es `null` en muchas personas naturales. | Campo | Tipo | Descripción | |---|---|---| | `identificacion` | string | Identificación consultada. | | `tipoIdentificacion` | string | Tipo detectado: `Cedula`, `RucPersonaNatural`, `RucSociedadPrivada`, `RucSociedadPublica`, `Pasaporte` o `Desconocido`. | | `nombreCompleto` | string | Nombre de la persona natural o razón social de la sociedad. Úsalo cuando `razonSocial` venga `null`. | | `razonSocial` | string | Razón social registrada. Es el valor recomendado para `razonSocialComprador` o `razonSocialProveedor`. | | `nombreComercial` | string | Nombre comercial, si existe. | | `clase` | string | `PersonaNatural`, `Sociedad` o `SociedadPublica`. | | `estado` | string | Estado en el catastro, tal como lo publica el SRI, por ejemplo `ACTIVO`. Compara contra `ACTIVO` y trata cualquier otro texto como "no activo". | | `regimen` | string | Régimen tributario, tal como lo publica el SRI. | | `actividadEconomicaPrincipal` | string | Descripción de la actividad económica principal. | | `obligadoLlevarContabilidad` | boolean | `true` si está obligado a llevar contabilidad. | | `agenteRetencion` | boolean | `true` si es agente de retención. | | `contribuyenteEspecial` | boolean | `true` si es contribuyente especial. | | `fechaInicioActividades` | string | Fecha y hora de inicio de actividades, en formato `yyyy-MM-ddTHH:mm:ss` y sin zona horaria. | | `fechaCese` | string | Fecha de cese de actividades. Vale `null` si sigue activo. | | `fechaReinicioActividades` | string | Fecha de reinicio de actividades. Vale `null` si no aplica. | | `fechaActualizacion` | string | Última actualización de los datos en el catastro. | | `representantesLegales` | array | Representantes legales, que suelen venir en las sociedades. Puede ser `[]` o `null`. | | `representantesLegales[].identificacion` | string | Identificación del representante. | | `representantesLegales[].nombre` | string | Nombre del representante. | | `establecimientos` | array | Establecimientos del contribuyente, con el mismo formato que en [Establecimientos de un RUC](/v1/guias/consulta-establecimientos). | | `establecimientos[].numero` | string | Código del establecimiento, de 3 dígitos, por ejemplo `001`. Es el valor que usas en `infoTributaria.estab`. | | `establecimientos[].nombreComercial` | string | Nombre comercial del establecimiento. | | `establecimientos[].tipo` | string | Tipo, tal como lo publica el SRI, por ejemplo `MATRIZ`. Para decidir si es la matriz, usa `esMatriz`. | | `establecimientos[].direccionCompleta` | string | Dirección registrada. | | `establecimientos[].estado` | string | `ABIERTO` o `CERRADO`. | | `establecimientos[].esMatriz` | boolean | `true` si es la matriz. | | `estadoTributario` | object | Situación de deudas, impugnaciones y remisiones. Puede venir `null`. | | `estadoTributario.tieneDeuda` | boolean | `true` si registra deudas. | | `estadoTributario.tieneImpugnacion` | boolean | `true` si registra impugnaciones. | | `estadoTributario.tieneRemision` | boolean | `true` si registra remisiones. | | `estadoTributario.resumenDeuda` | string | Resumen de la deuda, si existe. | | `estadoTributario.resumenImpugnacion` | string | Resumen de la impugnación, si existe. | | `estadoTributario.resumenRemision` | string | Resumen de la remisión, si existe. | | `estadoTributario.consultadoEn` | string | Momento en que se obtuvo el estado tributario. | | `fuenteOrigen` | string | Fuente que aportó los datos, por ejemplo `SriCatastro`. | | `consultadoEn` | string | Momento de la consulta. | ## Estados de este endpoint Los errores tienen el formato de cualquier error de la API, con los campos `estado`, `codEstado`, `msgError` y `errores`. En los errores de validación, `errores` trae el detalle de cada problema, como en este ejemplo; en los demás viene como una lista vacía. ```json { "estado": "rechazado", "codEstado": 3012, "msgError": "Filtros inválidos.", "errores": [ "fuente debe ser Todas o SriCatastro." ] } ``` | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La consulta encontró al contribuyente. | Lee los datos. | | 3003 (`solicitud_invalida`) | 400 | La identificación tiene un formato que la fuente no acepta, o `fusionar` no es `true` ni `false`. | Corrige la identificación o el parámetro. | | 3012 (`filtros_invalidos`) | 400 | `fuente` no es `Todas` ni `SriCatastro`. | Corrige `fuente` u omítelo. | | 3007 (`version_no_soportada`) | 400 | Enviaste `X-Api-Version` con una versión no admitida. | Quita la cabecera o envía la versión vigente. | | 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa `X-Api-Key`, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o revisa los proxies o balanceadores entre tu servidor y la API. | | 3011 (`acceso_denegado`) | 403 | Tu API Key está limitada y no incluye el scope `sri:consultar`. | Crea una API Key con ese scope en **Cuenta > API Keys**. | | 3013 (`no_encontrado`) | 404 | La identificación no existe en el catastro o ninguna fuente tuvo resultado. | Verifica el número y, si el usuario lo escribió, pídele que lo confirme. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes de tu API Key o la fuente limitó las consultas. | Espera los segundos que indica `Retry-After` y reintenta. | | 5001 (`error_interno`) | 500 | Ocurrió un error interno. | Reintenta con una espera y, si persiste, reporta el valor de `X-Correlation-Id`. | | 5003 (`error_dependencia`) | 502 | La fuente de datos reportó un error o no está disponible. | Reintenta con una espera creciente, por ejemplo de 5, 15 y 60 segundos. | | 5002 (`servicio_no_disponible`) | 503 | El servicio de consultas no está disponible temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. | | 5004 (`tiempo_agotado`) | 504 | La fuente no respondió a tiempo. | Reintenta con una espera. Si necesitas una respuesta más rápida, prueba con `fusionar=false`. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Validar identificación](/v1/guias/consulta-identificacion): comprueba el dígito verificador antes de consultar o de emitir. - [Contribuyentes por nombre](/v1/guias/consulta-contribuyente-nombre): encuentra la identificación cuando solo conoces el nombre. - [Factura](/v1/guias/emision-01): usa los datos consultados para llenar al comprador. - [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno. --- # Contribuyentes por nombre Busca contribuyentes en el catastro del SRI por apellidos y nombres, o por el inicio de su razón social, y devuelve sus identificaciones. A veces solo conoces el nombre de un cliente o un proveedor y necesitas su cédula o su RUC. Con este endpoint puedes buscar ese nombre en el catastro público del [SRI](/v1/guias/glosario) y obtener las coincidencias, cada una con su identificación, su clase y su estado. Al terminar esta página sabrás cómo escribir la búsqueda para personas y para sociedades, cómo leer las coincidencias y qué hacer cuando no hay resultados. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas. > La búsqueda lee el catastro público del SRI en ambos ambientes. ## Endpoint ``` GET /v1/consultas/contribuyentes?apellidos={apellidos}&nombres={nombres}&clase={clase}&max={max} X-Api-Key: ``` | Cabecera | Obligatoria | Descripción | |---|---|---| | `X-Api-Key` | Sí | Tu [API Key](/v1/guias/glosario). | | `X-Api-Version` | No | Versión del contrato. Si la omites, se usa la vigente. | La respuesta es un **arreglo** de coincidencias en el primer nivel del JSON. Esta consulta **no consume cupo** de documentos, pero sí cuenta para el límite de solicitudes por minuto de tu API Key, que se explica en [Límites](/v1/guias/limites). ## Cuándo usarlo - **Dar de alta a un cliente o proveedor del que solo tienes el nombre.** Busca por nombre, muestra las coincidencias a tu usuario y, cuando elija una, guarda su `identificacion`. Después completa la ficha con [Contribuyente por identificación](/v1/guias/consulta-contribuyente). - **Corregir identificaciones mal registradas** en tu ERP, comparando el nombre con el catastro. Te recomendamos no usar esta búsqueda para elegir automáticamente al comprador de un comprobante, porque puede haber varias personas con el mismo nombre. Deja que tu usuario confirme la coincidencia. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). ## Parámetros | Nombre | Dónde | Tipo | Obligatorio | Descripción | |---|---|---|---|---| | `apellidos` | consulta | string | Sí | Para personas naturales, sus apellidos, por ejemplo `PEREZ LOPEZ`. Para sociedades, el **inicio** de la razón social, por ejemplo `COMERCIAL DE`; un fragmento del medio o del final puede no encontrar coincidencias. Si falta o está vacío, la API responde 400 con el `codEstado` 3012 (`filtros_invalidos`). | | `nombres` | consulta | string | No | Nombres de la persona natural, por ejemplo `JUAN`. Sirve para acotar la búsqueda. | | `clase` | consulta | string | No | `PersonaNatural`, el valor por defecto, `Sociedad` o `SociedadPublica`. No distingue mayúsculas. Con otro valor la API responde 400 con el `codEstado` 3012 (`filtros_invalidos`). Para buscar una empresa privada, envía `Sociedad`. | | `max` | consulta | integer | No | Número máximo de coincidencias, de 1 a 30. Por defecto es 10. Fuera de ese rango la API responde 400 con el `codEstado` 3012 (`filtros_invalidos`), y con un valor que no es entero responde 400 con el `codEstado` 3003 (`solicitud_invalida`). | Codifica los valores para la URL; por ejemplo, el espacio se escribe `%20`, como en `PEREZ%20LOPEZ`. Si usas nuestros SDK o las bibliotecas HTTP de los ejemplos de Python, la codificación se hace por ti. ## Ejemplo Los nombres del ejemplo son genéricos, así que la respuesta depende de lo que haya en el catastro real. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes?apellidos=PEREZ%20LOPEZ&nombres=JUAN&clase=PersonaNatural&max=10" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); string ruta = "/v1/consultas/contribuyentes?apellidos=" + Uri.EscapeDataString("PEREZ LOPEZ") + "&nombres=" + Uri.EscapeDataString("JUAN") + "&clase=PersonaNatural&max=10"; using HttpResponseMessage respuesta = await http.GetAsync(ruta); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, params={"apellidos": "PEREZ LOPEZ", "nombres": "JUAN", "clase": "PersonaNatural", "max": 10}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs const consulta = new URLSearchParams({ apellidos: 'PEREZ LOPEZ', nombres: 'JUAN', clase: 'PersonaNatural', max: '10' }); const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes?' + consulta, { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php 'PEREZ LOPEZ', 'nombres' => 'JUAN', 'clase' => 'PersonaNatural', 'max' => 10], '', '&', PHP_QUERY_RFC3986); $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; // Dentro de: public static void main(String[] args) throws Exception String apellidos = URLEncoder.encode("PEREZ LOPEZ", StandardCharsets.UTF_8).replace("+", "%20"); HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes?apellidos=" + apellidos + "&nombres=JUAN&clase=PersonaNatural&max=10")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); IReadOnlyList encontrados = await client.BuscarContribuyentesAsync("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10); foreach (BusquedaContribuyente c in encontrados) { Console.WriteLine(c.Identificacion + " " + c.NombreCompleto); } ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) encontrados = client.buscar_contribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10) for contribuyente in encontrados: print(contribuyente.identificacion, contribuyente.nombre_completo) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const encontrados = await client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10); for (const contribuyente of encontrados) { console.log(contribuyente.identificacion, contribuyente.nombreCompleto); } ``` ```php-sdk buscarContribuyentes('PEREZ LOPEZ', 'JUAN', 'PersonaNatural', 10); foreach ($encontrados as $contribuyente) { echo $contribuyente->identificacion . ' ' . $contribuyente->nombreCompleto . PHP_EOL; } ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.BusquedaContribuyente; import java.util.List; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); List encontrados = client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10); for (BusquedaContribuyente contribuyente : encontrados) { System.out.println(contribuyente.identificacion() + " " + contribuyente.nombreCompleto()); } ``` ```bash-cli # Resultado esperado: hasta 10 coincidencias con su identificación y nombre, en tabla. ecuafact ruc buscar --apellidos "PEREZ LOPEZ" --nombres JUAN --clase PersonaNatural --max 10 --entorno sandbox ``` El resultado esperado es un 200 con un arreglo de hasta `max` coincidencias. ## Respuesta La API responde `200 OK`. Los valores de este ejemplo son ilustrativos. ```json [ { "identificacion": "0123456789", "tipoIdentificacion": "Cedula", "nombreCompleto": "PEREZ LOPEZ JUAN CARLOS", "clase": "PersonaNatural", "estado": "ACTIVO", "fuenteOrigen": "SriCatastro" } ] ``` Cada elemento del arreglo trae estos campos, y cualquiera puede venir `null` si la fuente no tiene el dato. | Campo | Tipo | Descripción | |---|---|---| | `identificacion` | string | Cédula, RUC o pasaporte del contribuyente encontrado. Guárdala para consultas posteriores. | | `tipoIdentificacion` | string | `Cedula`, `RucPersonaNatural`, `RucSociedadPrivada`, `RucSociedadPublica`, `Pasaporte` o `Desconocido`. | | `nombreCompleto` | string | Nombre de la persona natural o razón social. | | `clase` | string | `PersonaNatural`, `Sociedad` o `SociedadPublica`. | | `estado` | string | Estado en el catastro, tal como lo publica el SRI, por ejemplo `ACTIVO`. | | `fuenteOrigen` | string | Fuente que aportó el dato, por ejemplo `SriCatastro`. | Cuando no hay coincidencias, la respuesta puede ser un 200 con un arreglo vacío (`[]`) o un 404 con el `codEstado` 3013 (`no_encontrado`), según lo que informe la fuente. Trata ambos casos como "sin resultados". ## Estados de este endpoint | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La búsqueda se realizó, con o sin coincidencias. | Lee el arreglo; un `[]` significa que no hubo resultados. | | 3012 (`filtros_invalidos`) | 400 | Falta `apellidos`, `clase` no es un valor permitido o `max` está fuera de 1 a 30. El detalle llega en `errores`, por ejemplo `["max debe estar entre 1 y 30."]`. | Corrige los parámetros. | | 3003 (`solicitud_invalida`) | 400 | `max` no es un número entero, o la fuente rechazó el formato de la búsqueda. | Corrige los parámetros. | | 3007 (`version_no_soportada`) | 400 | Enviaste `X-Api-Version` con una versión no admitida. | Quita la cabecera o envía la versión vigente. | | 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa `X-Api-Key`, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o revisa los proxies o balanceadores entre tu servidor y la API. | | 3011 (`acceso_denegado`) | 403 | Tu API Key está limitada y no incluye el scope `sri:consultar`. | Crea una API Key con ese scope en **Cuenta > API Keys**. | | 3013 (`no_encontrado`) | 404 | La fuente no encontró coincidencias. | Prueba con menos palabras en `apellidos` o sin `nombres`. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes de tu API Key o la fuente limitó las consultas. | Espera los segundos que indica `Retry-After` y reintenta. Si buscas mientras el usuario escribe, espera a que termine, por ejemplo 400 ms sin teclear, antes de llamar. | | 5001 (`error_interno`) | 500 | Ocurrió un error interno. | Reintenta con una espera y, si persiste, reporta el valor de `X-Correlation-Id`. | | 5003 (`error_dependencia`) | 502 | La fuente de datos reportó un error o no está disponible. | Reintenta con una espera creciente, por ejemplo de 5, 15 y 60 segundos. | | 5002 (`servicio_no_disponible`) | 503 | El servicio de consultas no está disponible temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. | | 5004 (`tiempo_agotado`) | 504 | La fuente no respondió a tiempo. | Reintenta con una espera. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Contribuyente por identificación](/v1/guias/consulta-contribuyente): obtiene la ficha completa de la coincidencia que elegiste. - [Validar identificación](/v1/guias/consulta-identificacion): comprueba el formato de una cédula o RUC sin consultar al SRI. - [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno. --- # Establecimientos de un RUC Lista los establecimientos que un RUC tiene registrados en el SRI, con su dirección y si están abiertos o cerrados. Un [establecimiento](/v1/guias/glosario) es un local que el [contribuyente](/v1/guias/glosario) tiene registrado en el [SRI](/v1/guias/glosario), sea la matriz o una sucursal. Su código de 3 dígitos es el `estab` con el que numeras tus comprobantes. Con este endpoint puedes consultar los establecimientos de un RUC, con su código, su nombre comercial, su dirección y su estado. Te sirve para comprobar que un establecimiento existe antes de emitir con él o para llenar direcciones sin escribirlas a mano. Al terminar esta página sabrás cómo filtrar el listado y cómo leer cada establecimiento. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas. > La consulta lee el catastro público del SRI en ambos ambientes. ## Endpoint ``` GET /v1/consultas/establecimientos/{ruc}?filtro={filtro} X-Api-Key: ``` | Cabecera | Obligatoria | Descripción | |---|---|---| | `X-Api-Key` | Sí | Tu [API Key](/v1/guias/glosario). | | `X-Api-Version` | No | Versión del contrato. Si la omites, se usa la vigente. | La respuesta es un objeto JSON con los campos en el primer nivel. Esta consulta **no consume cupo** de documentos, pero sí cuenta para el límite de solicitudes por minuto de tu API Key, que se explica en [Límites](/v1/guias/limites). ## Cuándo usarlo - **Elegir el establecimiento con el que emites.** Antes de emitir con el `estab` `002`, comprueba que ese establecimiento existe y está `ABIERTO` en el RUC emisor. - **Llenar direcciones.** Usa `direccionCompleta` como dirección del establecimiento emisor o, en una guía de remisión, como `dirPartida` o `dirDestinatario` cuando el destino es una sucursal de tu cliente. - **Mostrar las sucursales de un cliente o proveedor** en tu ERP. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). - [ ] Para ver datos reales, un RUC que exista en el catastro del SRI, por ejemplo el RUC de tu empresa. ## Parámetros | Nombre | Dónde | Tipo | Obligatorio | Descripción | |---|---|---|---|---| | `ruc` | ruta | string | Sí | RUC de 13 dígitos del contribuyente. La API elimina los espacios al inicio y al final. | | `filtro` | consulta | string | No | Qué establecimientos devolver, según la tabla siguiente. No distingue mayúsculas. Con otro valor, la API responde 400 con el `codEstado` 3012 (`filtros_invalidos`). | | `filtro` | Devuelve | |---|---| | `Todos` (por defecto) | Todos los establecimientos, abiertos y cerrados. | | `SoloActivos` | Solo los establecimientos con `estado` `ABIERTO`. | | `SoloCerrados` | Solo los establecimientos con `estado` `CERRADO`. | | `SoloMatriz` | Solo la matriz, es decir, el establecimiento con `esMatriz` en `true`. | | `SoloSucursales` | Solo los establecimientos que no son la matriz. | ## Ejemplo El RUC `0123456789001` es el identificador de prueba de esta documentación y **no existe en el catastro**; para ver datos reales, reemplázalo por el RUC de tu propia empresa. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/establecimientos/0123456789001?filtro=SoloActivos" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/consultas/establecimientos/0123456789001?filtro=SoloActivos"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/consultas/establecimientos/0123456789001", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, params={"filtro": "SoloActivos"}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consultas/establecimientos/0123456789001?filtro=SoloActivos', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/consultas/establecimientos/0123456789001?filtro=SoloActivos")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); EstablecimientosContribuyente resultado = await client.ListarEstablecimientosAsync("0123456789001", "SoloActivos"); foreach (EstablecimientoConsulta e in resultado.Establecimientos ?? new()) { Console.WriteLine(e.Numero + " " + e.Estado + " " + e.DireccionCompleta); } ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) resultado = client.listar_establecimientos("0123456789001", "SoloActivos") for e in resultado.establecimientos or []: print(e.numero, e.estado, e.direccion_completa) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const resultado = await client.listarEstablecimientos("0123456789001", "SoloActivos"); for (const e of resultado.establecimientos ?? []) { console.log(e.numero, e.estado, e.direccionCompleta); } ``` ```php-sdk listarEstablecimientos('0123456789001', 'SoloActivos'); foreach ($resultado->establecimientos ?? [] as $e) { echo $e->numero . ' ' . $e->estado . ' ' . $e->direccionCompleta . PHP_EOL; } ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.EstablecimientoConsulta; import com.ecuafact.sdk.contracts.EstablecimientosContribuyente; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); EstablecimientosContribuyente resultado = client.listarEstablecimientos("0123456789001", "SoloActivos"); for (EstablecimientoConsulta e : resultado.establecimientos()) { System.out.println(e.numero() + " " + e.estado() + " " + e.direccionCompleta()); } ``` ```bash-cli # Resultado esperado: con un RUC que existe, sus establecimientos abiertos en tabla. # Con el RUC de prueba 0123456789001, un error 404 con el `codEstado` 3013 (`no_encontrado`). ecuafact establecimientos 0123456789001 --filtro SoloActivos --entorno sandbox ``` Con un RUC que existe, el resultado esperado es un 200 con el objeto que se describe en la sección siguiente. Con `0123456789001` recibes un 404 con el `codEstado` 3013 (`no_encontrado`) y el mensaje "Recurso no encontrado.". ## Respuesta La API responde `200 OK`. Los valores de este ejemplo son ilustrativos. ```json { "ruc": "0123456789001", "filtro": "SoloActivos", "cantidad": 2, "establecimientos": [ { "numero": "001", "nombreComercial": "COMERCIAL DE PRUEBA", "tipo": "MATRIZ", "direccionCompleta": "AV. DE PRUEBA 123 Y CALLE FICTICIA", "estado": "ABIERTO", "esMatriz": true }, { "numero": "002", "nombreComercial": "COMERCIAL DE PRUEBA SUCURSAL NORTE", "tipo": "LOCAL COMERCIAL", "direccionCompleta": "CALLE FICTICIA 456", "estado": "ABIERTO", "esMatriz": false } ] } ``` Cualquier campo puede venir `null` si la fuente no tiene el dato. | Campo | Tipo | Descripción | |---|---|---| | `ruc` | string | RUC consultado. | | `filtro` | string | Filtro aplicado, con su nombre canónico: `Todos`, `SoloActivos`, `SoloCerrados`, `SoloMatriz` o `SoloSucursales`. | | `cantidad` | integer | Número de establecimientos devueltos después de aplicar el filtro. | | `establecimientos` | array | Establecimientos que cumplen el filtro. Puede venir vacío (`[]`). | | `establecimientos[].numero` | string | Código del establecimiento, de 3 dígitos. Es el valor de `infoTributaria.estab`. | | `establecimientos[].nombreComercial` | string | Nombre comercial del establecimiento. | | `establecimientos[].tipo` | string | Tipo, tal como lo publica el SRI, por ejemplo `MATRIZ`. Para decidir si es la matriz, usa `esMatriz`. | | `establecimientos[].direccionCompleta` | string | Dirección registrada en el SRI. | | `establecimientos[].estado` | string | `ABIERTO` o `CERRADO`. | | `establecimientos[].esMatriz` | boolean | `true` si es la matriz. | ## Estados de este endpoint | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La consulta se realizó. | Lee `establecimientos`. Si `cantidad` es 0, ningún establecimiento cumple el filtro. | | 3012 (`filtros_invalidos`) | 400 | `filtro` no es uno de los valores permitidos. El detalle llega en `errores`. | Corrige `filtro` u omítelo. | | 3003 (`solicitud_invalida`) | 400 | El RUC tiene un formato que la fuente no acepta. | Corrige el RUC, que debe tener 13 dígitos. | | 3007 (`version_no_soportada`) | 400 | Enviaste `X-Api-Version` con una versión no admitida. | Quita la cabecera o envía la versión vigente. | | 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa `X-Api-Key`, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o revisa los proxies o balanceadores entre tu servidor y la API. | | 3011 (`acceso_denegado`) | 403 | Tu API Key está limitada y no incluye el scope `sri:consultar`. | Crea una API Key con ese scope en **Cuenta > API Keys**. | | 3013 (`no_encontrado`) | 404 | El RUC no existe en el catastro o no tiene establecimientos registrados. | Verifica el RUC. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes de tu API Key o la fuente limitó las consultas. | Espera los segundos que indica `Retry-After` y reintenta. | | 5001 (`error_interno`) | 500 | Ocurrió un error interno. | Reintenta con una espera y, si persiste, reporta el valor de `X-Correlation-Id`. | | 5003 (`error_dependencia`) | 502 | La fuente de datos reportó un error o no está disponible. | Reintenta con una espera creciente, por ejemplo de 5, 15 y 60 segundos. | | 5002 (`servicio_no_disponible`) | 503 | El servicio de consultas no está disponible temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. | | 5004 (`tiempo_agotado`) | 504 | La fuente no respondió a tiempo. | Reintenta con una espera. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Contribuyente por identificación](/v1/guias/consulta-contribuyente): obtiene la ficha completa del RUC, incluidos sus establecimientos. - [Guía de remisión](/v1/guias/emision-06): usa las direcciones de los establecimientos en el traslado. - [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno. --- # Validar identificación Comprueba el formato y el dígito verificador de una cédula, un RUC o un pasaporte, sin consultar al SRI. Antes de emitir un comprobante, puedes comprobar que la identificación del comprador esté bien escrita. Este endpoint revisa el formato del número y su dígito verificador, te dice si es una cédula, un RUC o un pasaporte y te devuelve el valor normalizado. Como no consulta al [SRI](/v1/guias/glosario), te responde rápido. Ten en cuenta que la API responde 200 tanto si el número es válido como si no lo es; lo que decide es el campo `valido` de la respuesta. Al terminar esta página sabrás qué reglas se comprueban y cómo usar el resultado para llenar el tipo de identificación del comprador. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas, > y la validación se comporta igual en ambos ambientes. ## Endpoint ``` GET /v1/consultas/identificacion/validar/{numero} X-Api-Key: ``` | Cabecera | Obligatoria | Descripción | |---|---|---| | `X-Api-Key` | Sí | Tu [API Key](/v1/guias/glosario). | | `X-Api-Version` | No | Versión del contrato. Si la omites, se usa la vigente. | La respuesta es un objeto JSON con los campos en el primer nivel. Esta consulta **no consume cupo** de documentos, pero sí cuenta para el límite de solicitudes por minuto de tu API Key, que se explica en [Límites](/v1/guias/limites). > [!NOTE] > Esta validación es solo de formato y **no confirma que la persona o empresa > exista** en el SRI. Para confirmar que existe, usa > [Contribuyente por identificación](/v1/guias/consulta-contribuyente). ## Cuándo usarlo - **Validar la cédula o el RUC del comprador antes de emitir.** Llama a esta consulta cuando tu usuario captura el número en el formulario de facturación. Si `valido` es `false`, pídele que lo corrija antes de enviar el comprobante, y así evitas un rechazo del SRI por una identificación mal escrita. - **Elegir el tipo de identificación del comprador.** El campo `tipo` te dice si el número es una cédula, un RUC o un pasaporte, y con eso llenas `tipoIdentificacionComprador`: `05` para cédula, `04` para RUC y `06` para pasaporte. Los códigos están en [Catálogos](/v1/guias/catalogos). - **Limpiar los datos de tu ERP** en lote, sin depender de la disponibilidad del SRI. ## Qué se valida | Tipo | Regla que se comprueba | |---|---| | Cédula | Tiene 10 dígitos y su dígito verificador cumple el módulo 10. | | RUC de persona natural | Tiene 13 dígitos: una cédula válida seguida de un código de establecimiento, por ejemplo `001`. La respuesta trae la cédula en `cedulaBaseDelRuc`. | | RUC de sociedad privada o pública | Tiene 13 dígitos con la estructura de RUC de sociedad. No se exige el dígito verificador módulo 11. | | Pasaporte | Es alfanumérico, de 5 a 20 caracteres. | La cédula de prueba de esta documentación, `0123456789`, y el RUC de prueba `0123456789001` **no pasan** el módulo 10, así que con ellos la respuesta trae `valido` en `false`. Para ver una respuesta con `valido` en `true`, prueba con tu propia cédula o con el RUC de tu empresa. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). ## Parámetros | Nombre | Dónde | Tipo | Obligatorio | Descripción | |---|---|---|---|---| | `numero` | ruta | string | Sí | Cédula, RUC o pasaporte a validar. La API elimina los espacios al inicio y al final, y `normalizado` muestra el valor sin separadores. | ## Ejemplo ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/identificacion/validar/0123456789001" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/consultas/identificacion/validar/0123456789001"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/consultas/identificacion/validar/0123456789001", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consultas/identificacion/validar/0123456789001', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/consultas/identificacion/validar/0123456789001")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); ValidacionIdentificacion resultado = await client.ValidarIdentificacionAsync("0123456789001"); if (resultado.Valido == true) { Console.WriteLine("Formato valido: " + resultado.Tipo); } else { Console.WriteLine("Corrige el numero: " + resultado.Mensaje); } ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) resultado = client.validar_identificacion("0123456789001") if resultado.valido: print("Formato valido:", resultado.tipo) else: print("Corrige el numero:", resultado.mensaje) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const resultado = await client.validarIdentificacion("0123456789001"); if (resultado.valido === true) { console.log("Formato valido:", resultado.tipo); } else { console.log("Corrige el numero:", resultado.mensaje); } ``` ```php-sdk validarIdentificacion('0123456789001'); if ($resultado->valido === true) { echo 'Formato valido: ' . $resultado->tipo . PHP_EOL; } else { echo 'Corrige el numero: ' . $resultado->mensaje . PHP_EOL; } ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.ValidacionIdentificacion; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); ValidacionIdentificacion resultado = client.validarIdentificacion("0123456789001"); if (Boolean.TRUE.equals(resultado.valido())) { System.out.println("Formato valido: " + resultado.tipo()); } else { System.out.println("Corrige el numero: " + resultado.mensaje()); } ``` ```bash-cli # Resultado esperado con 0123456789001: valido en false, porque la cédula de prueba no cumple el módulo 10. ecuafact identificacion validar 0123456789001 --entorno sandbox ``` Con `0123456789001`, el resultado esperado es un 200 con `valido` en `false`, porque la cédula base de prueba no cumple el módulo 10. Con un número real bien escrito recibes un 200 con `valido` en `true`. ## Respuesta La API responde `200 OK`. Esta es la respuesta con un RUC de persona natural **válido**; en lugar de `0123456789001` verás el RUC real que validaste, y los textos de `mensaje` son ilustrativos. ```json { "entrada": "0123456789001", "normalizado": "0123456789001", "valido": true, "tipo": "RucPersonaNatural", "longitud": 13, "esSoloDigitos": true, "cedulaBaseDelRuc": "0123456789", "mensaje": "Formato de RUC de persona natural aceptado; confirme su registro en el SRI." } ``` Y esta es la respuesta con un número **inválido**, que también llega con un 200: ```json { "entrada": "0123456789", "normalizado": "0123456789", "valido": false, "tipo": "Cedula", "longitud": 10, "esSoloDigitos": true, "cedulaBaseDelRuc": null, "mensaje": "El digito verificador de la cedula no es valido." } ``` | Campo | Tipo | Descripción | |---|---|---| | `entrada` | string | Número tal como lo enviaste. | | `normalizado` | string | Número sin espacios ni separadores. Guarda este valor en tu sistema. | | `valido` | boolean | `true` si el formato y el dígito verificador son correctos. **Es el campo que decide**, así que no uses el código HTTP para saber si el número es válido. | | `tipo` | string | Tipo detectado. Sus valores están en la tabla siguiente. | | `longitud` | integer | Cantidad de caracteres de `normalizado`. | | `esSoloDigitos` | boolean | `true` si el número contiene solo dígitos; es `false` en los pasaportes alfanuméricos. | | `cedulaBaseDelRuc` | string | Cédula contenida en un RUC de persona natural, es decir, sus primeros 10 dígitos. Vale `null` en los demás tipos. | | `mensaje` | string | Explicación del resultado en lenguaje natural. Puedes mostrarla a tu usuario, pero no la uses para programar. | | `tipo` | Significado | `tipoIdentificacionComprador` | |---|---|---| | `Cedula` | Cédula de identidad, de 10 dígitos. | `05` | | `RucPersonaNatural` | RUC de una persona natural, formado por la cédula y el establecimiento. | `04` | | `RucSociedadPrivada` | RUC de una sociedad privada. | `04` | | `RucSociedadPublica` | RUC de una entidad pública. | `04` | | `Pasaporte` | Pasaporte alfanumérico, de 5 a 20 caracteres. | `06` | | `Desconocido` | El número no coincide con ningún tipo. Trátalo como inválido. | - | ## Estados de este endpoint | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La validación se realizó, con `valido` en `true` o en `false`. | Revisa `valido`. Si es `false`, pide al usuario que corrija el número. | | 3003 (`solicitud_invalida`) | 400 | El número tiene caracteres que no se pueden validar. | Corrige el número. | | 3007 (`version_no_soportada`) | 400 | Enviaste `X-Api-Version` con una versión no admitida. | Quita la cabecera o envía la versión vigente. | | 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa `X-Api-Key`, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o revisa los proxies o balanceadores entre tu servidor y la API. | | 3011 (`acceso_denegado`) | 403 | Tu API Key está limitada y no incluye el scope `sri:consultar`. | Crea una API Key con ese scope en **Cuenta > API Keys**. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes de tu API Key o la consulta se limitó temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. Valida cuando el usuario sale del campo, no en cada tecla. | | 5001 (`error_interno`) | 500 | Ocurrió un error interno. | Reintenta con una espera y, si persiste, reporta el valor de `X-Correlation-Id`. | | 5003 (`error_dependencia`) | 502 | La consulta no pudo completarse por un error temporal del servicio. | Reintenta con una espera. | | 5002 (`servicio_no_disponible`) | 503 | El servicio de consultas no está disponible temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. | | 5004 (`tiempo_agotado`) | 504 | La consulta no respondió a tiempo. | Reintenta con una espera. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Contribuyente por identificación](/v1/guias/consulta-contribuyente): confirma que el número existe y obtiene la razón social. - [Factura](/v1/guias/emision-01): usa la identificación validada en `identificacionComprador`. - [Catálogos](/v1/guias/catalogos): códigos de tipo de identificación y demás tablas del SRI. - [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno. --- # Decodificar clave de acceso Comprueba que una clave de acceso esté bien formada y devuelve sus partes: fecha, tipo de comprobante, RUC, ambiente, serie y secuencial. La [clave de acceso](/v1/guias/glosario) es el identificador único de 49 dígitos de un comprobante electrónico. Cada grupo de dígitos tiene un significado fijo, así que de la clave puedes leer la fecha de emisión, el tipo de comprobante, el RUC del emisor, el ambiente y el número del comprobante. Este endpoint revisa su largo y su dígito verificador y te devuelve esas partes ya separadas. Al terminar esta página sabrás cómo está formada una clave de acceso, cómo se calcula su dígito verificador y cómo usar sus partes, por ejemplo, para referenciar el documento que modifica una nota de crédito. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas, > y la decodificación se comporta igual en ambos ambientes. ## Endpoint ``` GET /v1/consultas/comprobantes/decodificar/{claveAcceso} X-Api-Key: ``` | Cabecera | Obligatoria | Descripción | |---|---|---| | `X-Api-Key` | Sí | Tu [API Key](/v1/guias/glosario). | | `X-Api-Version` | No | Versión del contrato. Si la omites, se usa la vigente. | La respuesta es un objeto JSON con los campos en el primer nivel. Esta consulta **no consume cupo** de documentos, pero sí cuenta para el límite de solicitudes por minuto de tu API Key, que se explica en [Límites](/v1/guias/limites). > [!NOTE] > Decodificar **no prueba que el comprobante esté autorizado** ni que exista en > el [SRI](/v1/guias/glosario), porque solo revisa la estructura y el dígito > verificador. Para conocer el estado de un comprobante que emitiste, usa el > [seguimiento](/v1/guias/consulta-operacion). ## Cuándo usarlo Cuando emites, te asignamos la clave de acceso y la recibes en el seguimiento o en el webhook. También la encuentras impresa en el RIDE de los comprobantes que te entregan tus proveedores. Puedes decodificarla en casos como estos: - **Validar una clave capturada a mano** antes de usarla, por ejemplo la clave del comprobante de sustento de una retención (`numAutDocSustento`). Así detectas aquí un dígito mal copiado, en lugar de recibir un rechazo del SRI. - **Obtener los datos del documento modificado** al emitir una nota de crédito o de débito. Con `establecimiento`, `puntoEmision` y `secuencial` armas `numDocModificado`, por ejemplo `001-001-000000123`, y con `fechaEmision` llenas `fechaEmisionDocSustento`, convirtiendo `yyyy-MM-dd` a `dd/MM/yyyy`. - **Clasificar las claves** que llegan a tu sistema por tipo de comprobante, emisor o ambiente, sin hacer otra consulta. ## Estructura de la clave de acceso La clave tiene 49 dígitos en posiciones fijas. Este es un ejemplo ficticio, con el dígito verificador correcto: `0710202601012345678900110010010000001231234567811`. | Posición | Largo | Contenido | Valor del ejemplo | Campo de la respuesta | |---|---|---|---|---| | 1-8 | 8 | Fecha de emisión, `ddMMyyyy` | `07102026` (07/10/2026) | `fechaEmision` (`2026-10-07`) | | 9-10 | 2 | Tipo de comprobante (`tipoDocumento`) | `01` (factura) | `tipo` | | 11-23 | 13 | RUC del emisor | `0123456789001` | `rucEmisor` | | 24 | 1 | Ambiente: `1` pruebas, `2` producción | `1` | `ambiente` | | 25-27 | 3 | Establecimiento (`estab`) | `001` | `establecimiento` | | 28-30 | 3 | Punto de emisión (`ptoEmi`) | `001` | `puntoEmision` | | 31-39 | 9 | Secuencial | `000000123` | `secuencial` | | 40-47 | 8 | Código numérico, que genera quien emite | `12345678` | `codigoNumerico` | | 48 | 1 | Tipo de emisión: `1` normal | `1` | `tipoEmision` | | 49 | 1 | Dígito verificador módulo 11 | `1` | `digitoVerificador` | Los establecimientos, puntos de emisión y secuenciales se explican en el [Glosario](/v1/guias/glosario). | Tipo de comprobante (posiciones 9-10) | Documento | |---|---| | `01` | Factura | | `03` | Liquidación de compra | | `04` | Nota de crédito | | `05` | Nota de débito | | `06` | Guía de remisión | | `07` | Comprobante de retención | ### Dígito verificador módulo 11 El dígito 49 se calcula sobre los primeros 48, siguiendo estos pasos: 1. Recorre los 48 dígitos **de derecha a izquierda** y multiplica cada uno por un factor que empieza en 2, sube hasta 7 y vuelve a 2, es decir, 2, 3, 4, 5, 6, 7, 2, 3 y así sucesivamente. 2. Suma los productos. 3. Calcula `11 - (suma mod 11)`. 4. Si el resultado es 11, el dígito es 0, y si es 10, el dígito es 1. En cualquier otro caso, el dígito es el resultado. En el ejemplo, la suma es 527, y como `527 mod 11 = 10`, el cálculo da `11 - 10 = 1`. Por eso el dígito verificador es 1. ## Antes de empezar - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox); cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion). - [ ] Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). ## Parámetros | Nombre | Dónde | Tipo | Obligatorio | Descripción | |---|---|---|---|---| | `claveAcceso` | ruta | string | Sí | Clave de acceso de 49 dígitos, sin espacios ni guiones. | ## Ejemplo ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync( "/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```python import os import requests r = requests.get( "https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811", headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}, timeout=30, ) print(r.status_code, r.text) ``` ```javascript // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // Dentro de: public static void main(String[] args) throws Exception HttpClient cliente = HttpClient.newHttpClient(); HttpRequest peticion = HttpRequest.newBuilder() .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811")) .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY")) .GET() .build(); HttpResponse respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString()); System.out.println(respuesta.statusCode() + " " + respuesta.body()); ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); ClaveAccesoDecodificada clave = await client.DecodificarClaveAccesoAsync( "0710202601012345678900110010010000001231234567811"); Console.WriteLine($"{clave.Valido} {clave.Tipo} {clave.Establecimiento}-{clave.PuntoEmision}-{clave.Secuencial}"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) clave = client.decodificar_clave_acceso("0710202601012345678900110010010000001231234567811") print(clave.valido, clave.tipo, f"{clave.establecimiento}-{clave.punto_emision}-{clave.secuencial}") ``` ```javascript-sdk // Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const clave = await client.decodificarClaveAcceso("0710202601012345678900110010010000001231234567811"); console.log(clave.valido, clave.tipo, `${clave.establecimiento}-${clave.puntoEmision}-${clave.secuencial}`); ``` ```php-sdk decodificarClaveAcceso('0710202601012345678900110010010000001231234567811'); echo ($clave->valido ? 'true' : 'false') . ' ' . $clave->tipo . ' ' . $clave->establecimiento . '-' . $clave->puntoEmision . '-' . $clave->secuencial . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.ClaveAccesoDecodificada; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); ClaveAccesoDecodificada clave = client.decodificarClaveAcceso("0710202601012345678900110010010000001231234567811"); System.out.println(clave.valido() + " " + clave.tipo() + " " + clave.establecimiento() + "-" + clave.puntoEmision() + "-" + clave.secuencial()); ``` ```bash-cli # Resultado esperado: la fecha, el tipo, el RUC, el ambiente, la serie y el secuencial de la clave. ecuafact clave decodificar 0710202601012345678900110010010000001231234567811 --entorno sandbox ``` El resultado esperado es un 200 con `valido` en `true` y las partes que aparecen en la tabla de estructura. Si cambias cualquier dígito de la clave, el dígito verificador deja de coincidir y la respuesta es un 400 con el `codEstado` 3003 (`solicitud_invalida`). ## Respuesta La API responde `200 OK` para la clave del ejemplo. El texto de `mensaje` es ilustrativo. ```json { "entrada": "0710202601012345678900110010010000001231234567811", "normalizada": "0710202601012345678900110010010000001231234567811", "valido": true, "longitud": 49, "fechaEmision": "2026-10-07", "tipo": "Factura", "rucEmisor": "0123456789001", "ambiente": "Pruebas", "establecimiento": "001", "puntoEmision": "001", "secuencial": "000000123", "codigoNumerico": "12345678", "tipoEmision": "1", "tipoEmisionDescripcion": "Normal", "digitoVerificador": "1", "mensaje": "Clave de acceso decodificada correctamente." } ``` | Campo | Tipo | Descripción | |---|---|---| | `entrada` | string | Clave tal como la enviaste. | | `normalizada` | string | Clave sin espacios ni separadores. | | `valido` | boolean | `true` si la clave tiene 49 dígitos y el dígito verificador es correcto. Usa los demás campos solo si es `true`. | | `longitud` | integer | Cantidad de dígitos, que en una clave correcta es 49. | | `fechaEmision` | string | Fecha de emisión en formato `yyyy-MM-dd`, tomada de las posiciones 1 a 8. En la Estructura del comprobante las fechas van como `dd/MM/yyyy`, así que conviértela antes de usarla. | | `tipo` | string | Nombre del tipo de comprobante de las posiciones 9 y 10, por ejemplo `Factura`. | | `rucEmisor` | string | RUC de 13 dígitos de quien emitió el comprobante, tomado de las posiciones 11 a 23. | | `ambiente` | string | `Pruebas` si el dígito es 1 o `Produccion` si es 2. Un comprobante de `Pruebas` no tiene validez fiscal. | | `establecimiento` | string | Código del establecimiento, de 3 dígitos. | | `puntoEmision` | string | Código del punto de emisión, de 3 dígitos. | | `secuencial` | string | Secuencial de 9 dígitos, con ceros a la izquierda. | | `codigoNumerico` | string | Código numérico de 8 dígitos. No tiene significado fiscal. | | `tipoEmision` | string | Dígito del tipo de emisión, por ejemplo `1`. | | `tipoEmisionDescripcion` | string | Descripción del tipo de emisión, por ejemplo `Normal`. | | `digitoVerificador` | string | Dígito verificador de la posición 49, como texto. | | `mensaje` | string | Explicación del resultado en lenguaje natural. No la uses para programar. | Cualquier campo puede venir `null` si la clave no se pudo descomponer. ## Estados de este endpoint Una clave con un largo o un dígito verificador incorrecto responde 400 con el `codEstado` 3003 (`solicitud_invalida`). Cuando recibas un 200, confirma además que `valido` es `true` antes de usar las partes, porque ese campo es el que decide y no el código HTTP. ```json { "estado": "rechazado", "codEstado": 3003, "msgError": "La solicitud no es válida.", "errores": [ "La solicitud de consulta tiene un formato invalido." ] } ``` | `codEstado` | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | - | 200 | La clave se descompuso. | Revisa `valido` antes de usar los datos. | | 3003 (`solicitud_invalida`) | 400 | La clave no tiene 49 dígitos, contiene otros caracteres o el dígito verificador no coincide. | Corrige la clave, que suele tener un dígito mal copiado. | | 3007 (`version_no_soportada`) | 400 | Enviaste `X-Api-Version` con una versión no admitida. | Quita la cabecera o envía la versión vigente. | | 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa `X-Api-Key`, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en **Cuenta > IP permitidas** o revisa los proxies o balanceadores entre tu servidor y la API. | | 3011 (`acceso_denegado`) | 403 | Tu API Key está limitada y no incluye el scope `sri:consultar`. | Crea una API Key con ese scope en **Cuenta > API Keys**. | | 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes de tu API Key o la consulta se limitó temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. | | 5001 (`error_interno`) | 500 | Ocurrió un error interno. | Reintenta con una espera y, si persiste, reporta el valor de `X-Correlation-Id`. | | 5003 (`error_dependencia`) | 502 | La consulta no pudo completarse por un error temporal del servicio. | Reintenta con una espera. | | 5002 (`servicio_no_disponible`) | 503 | El servicio de consultas no está disponible temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. | | 5004 (`tiempo_agotado`) | 504 | La consulta no respondió a tiempo. | Reintenta con una espera. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Siguientes pasos - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta si un comprobante que emitiste está autorizado. - [Nota de crédito](/v1/guias/emision-04): usa las partes de la clave para referenciar el documento modificado. - [Comprobante de retención](/v1/guias/emision-07): valida la clave del comprobante de sustento antes de emitir. - [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno. --- # Webhooks Recibe en tu servidor un aviso firmado cuando el SRI autoriza o rechaza un comprobante, o cuando no se pudo emitir, sin consultar el seguimiento. Cuando emites un comprobante, el resultado del SRI llega minutos después. En lugar de preguntar por él una y otra vez, puedes pedirnos que te avisemos. Configuras en el portal una URL de tu servidor y, cada vez que hay un resultado, te enviamos a esa URL un mensaje firmado con los datos del comprobante. Esta página explica cómo configurar ese destino en el portal, qué eventos recibes y qué hacer ante cada uno, cómo se reintentan las entregas y cómo escribir el endpoint que las recibe, con ejemplos en cada lenguaje. Al terminar tendrás un endpoint que verifica la firma, descarta los duplicados y responde a tiempo, probado primero en tu computador. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Configura y prueba tu destino primero > en el portal, `https://portal.mynexusapi.com`. ## 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: ```text Implementa en este proyecto el receptor de webhooks de Ecuafact con verificación de firma y pruébalo en local. 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/webhooks.md antes de escribir código; no inventes campos. Reutiliza el framework web y el lenguaje del proyecto y recomiéndame usar el verificador de webhooks del SDK de Ecuafact de ese lenguaje, con una frase de motivo (si prefiero no usarlo, impleméntalo según la guía); no inventes el formato de la firma, tómalo de la guía webhooks-firma. El endpoint debe leer el cuerpo crudo, verificar la firma de Ecuafact-Signature con el secreto del destino, rechazar firmas inválidas o con marca de tiempo fuera de tolerancia, deduplicar por eventType y resourceId, guardar el evento y responder 2xx rápido, procesando después. Lee el secreto del webhook de la variable ECUAFACT_WEBHOOK_SECRET sin mostrarlo; si falta, pídeme que lo copie del portal de pruebas (el destino de webhooks) y lo configure yo mismo en mi entorno o en un .env ignorado por git; nunca lo pegues en el chat ni lo imprimas. Decide por estado y codEstado del cuerpo, no por el texto de los mensajes. Prueba con el evento de prueba, con una firma válida y con una alterada, siguiendo la sección Probar en local de la guía. Reutiliza ECUAFACT_API_KEY sin mostrarla si necesitas emitir un comprobante que genere eventos. Ejecuta las pruebas e informa solo qué casos pasaron, la ruta del receptor y cualquier acción que yo deba hacer. ``` ## Conceptos Cuando emites, la API responde `202 Accepted`. Eso significa que el comprobante quedó **recibido**, pero todavía no tiene resultado del [SRI](/v1/guias/glosario), que llega minutos después. Tienes dos formas de conocer ese resultado: - **Seguimiento.** Tu sistema pregunta cada cierto tiempo con `GET /v1/operaciones/{idOperacion}`, como se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion). - **[Webhook](/v1/guias/glosario).** Te enviamos un `POST` a una URL tuya, el **destino**, cuando el resultado está listo. Cada envío es un **evento** y va firmado con un secreto que solo conocen tu servidor y nuestro servicio. Con los webhooks te ahorras las consultas repetidas y te enteras en cuanto hay resultado. Aun así, te recomendamos conservar el seguimiento como respaldo, porque un webhook puede llegar tarde, llegar repetido o no llegar si tu destino está pausado. Un destino puede recibir los eventos de **todos los contribuyentes** de tu integración o solo los de **un RUC**. En el portal, el destino nuevo queda para todos; por API puedes indicar un RUC concreto. Para saber a qué comprobante corresponde cada evento, usa el `idOperacion` y el `ruc` del cuerpo. ## Prerequisitos - [ ] Acceso al portal del cliente con permiso para editar **Eventos**. En pruebas y producción, el portal es `https://portal.mynexusapi.com`. - [ ] Un endpoint HTTPS público en el puerto 443 que acepte `POST`. Para desarrollar en tu computador, publícalo con un túnel, como se explica en [Probar en local](#probar-en-local). - [ ] Una [API Key](/v1/guias/glosario) de pruebas para emitir comprobantes que generen eventos. Si todavía no tienes una, crea tu [sandbox](/v1/guias/sandbox). - [ ] Un lugar seguro para guardar el secreto del destino, como la variable de entorno `ECUAFACT_WEBHOOK_SECRET` o tu gestor de secretos. ## Cómo funciona Desde que emites hasta que tu servidor procesa el resultado pasan estos pasos: 1. Emites un comprobante y recibes un 202 con el `idOperacion`. 2. Enviamos el comprobante al SRI y esperamos su resultado. 3. Con el resultado, te enviamos un evento (`document.authorized`, `document.rejected` o `document.failed`) a cada destino activo suscrito a ese evento. 4. Tu servidor lee el cuerpo crudo, verifica la firma, guarda el evento y responde un 2xx en menos de 15 segundos. 5. Si tu servidor no responde a tiempo, no se puede conectar o responde 408, 429 o 5xx, reintentamos con esperas crecientes, hasta 8 intentos. Si responde otro 4xx o un 3xx, la entrega queda **rechazada por tu servidor** y no se reintenta. El detalle está en [Reintentos y qué se considera fallo](#reintentos-y-que-se-considera-fallo). ## Configurar el destino en el portal Un destino es la URL de tu servidor que recibe los eventos. Créalo desde el portal del cliente siguiendo estos pasos: 1. Entra al portal del cliente y abre **Integración > Eventos**. 2. Pulsa **Nuevo destino**. 3. En **URL** escribe la dirección completa de tu endpoint, por ejemplo `https://erp.tu-empresa.com/webhooks/ecuafact`. 4. Marca los eventos que quieres recibir: **Documento autorizado** (`document.authorized`), **Documento rechazado** (`document.rejected`), **Documento no emitido** (`document.failed`) y **Operación requiere atención** (`operation.requires_attention`), que avisa una sola vez cuando un comprobante sigue `recibido` sin resultado confirmado. Los cuatro vienen marcados y debes dejar al menos uno. 5. Pulsa **Crear**. El portal muestra el **secreto** del destino. 6. Copia el secreto y guárdalo en la variable `ECUAFACT_WEBHOOK_SECRET` de tu servidor. 7. Pulsa **Probar** para recibir un evento de prueba y confirma en **Entregas** que su estado es **Entregado** y que la columna HTTP muestra 200. > [!WARNING] > El secreto se muestra **una sola vez**, al crear el destino o al rotarlo. Si lo > pierdes, usa **Rotar secreto** y actualiza tu servidor. Nunca lo publiques en > tu repositorio, en logs ni en el código del navegador, porque con él > cualquiera puede falsificar eventos. Cada ambiente tiene su propio portal y sus propios destinos, así que configura un destino en pruebas y otro en producción. Como el cuerpo del evento no indica el ambiente, usa una URL distinta para cada uno, por ejemplo `/webhooks/ecuafact/pruebas` y `/webhooks/ecuafact/produccion`. ### Requisitos de la URL La URL del destino debe cumplir estos requisitos. El portal rechaza al crear el destino una URL que no cumpla alguno de los cinco primeros; las redirecciones, en cambio, se detectan en cada entrega. | Requisito | Detalle | |---|---| | Esquema | Solo se admite `https://`. | | Puerto | Solo se admite el 443, que es el puerto por defecto de HTTPS. | | Credenciales en la URL | No se admiten (`https://usuario:clave@...`). Tu servidor autentica cada entrega con la firma. | | Formato | Hasta 2048 caracteres, sin espacios ni caracteres de control. | | Red | El nombre debe resolver a una IP pública. Se rechazan `localhost`, `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `100.64.0.0/10`, `0.0.0.0/8`, el resto de rangos reservados, y las IPv6 locales, de enlace local o multicast. | | Redirecciones | No se siguen. Una respuesta 3xx, por ejemplo 301 o 302, deja la entrega **rechazada por tu servidor**, sin reintentos. Registra la URL final. | ### Acciones del portal Cada destino tiene estas acciones en **Integración > Eventos**. | Acción | Qué hace | |---|---| | **Nuevo destino** | Crea un destino con su URL, sus eventos y un secreto nuevo. Para cambiar la URL de un destino, crea uno nuevo y deshabilita el anterior. | | **Probar** | Envía a ese destino el evento de prueba `operation.requires_attention`, descrito en [Evento de prueba](#evento-de-prueba). | | **Entregas** | Muestra las últimas 50 entregas del destino, con la fecha, el evento, el estado, el número de intento y el código HTTP que respondió tu servidor. | | **Intentos** | En la tabla de **Entregas**, muestra el historial de intentos de esa entrega, con la fecha, el número de intento, el resultado, el código HTTP, la causa del error y la duración en milisegundos. | | **Reenviar** | En la tabla de **Entregas**, vuelve a enviar ese evento ahora, con el mismo cuerpo y una firma nueva. | | **Rotar secreto** | Genera un secreto nuevo y lo muestra una vez. Las entregas siguientes se firman con el nuevo, como se explica en [Rotación del secreto](/v1/guias/webhooks-firma#rotacion-de-secreto). | | **Pausar** / **Reanudar** | Detiene o reactiva la entrega de eventos nuevos a ese destino. Las entregas que ya estaban programadas antes de la pausa siguen con sus reintentos. Un destino pausado no recibe el evento de **Probar**. | | **Deshabilitar** | Da de baja el destino. Un destino deshabilitado no se puede reactivar; para volver a recibir eventos, crea uno nuevo. | ## Administrar destinos por API Puedes administrar los destinos desde el Portal del Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP o con la API REST. Los SDK no administran destinos: solo verifican la firma de los webhooks que recibes. Si tu integración administra varios RUC o quieres automatizar el alta de destinos, usa los endpoints de webhooks con la cabecera `X-Api-Key`. Son la misma capacidad del portal, expuesta para clientes y socios, así que no necesitas una sesión del portal. Puedes listar, crear y consultar destinos, cambiar los eventos a los que están suscritos, rotar su secreto, probarlos, pausarlos, reanudarlos y deshabilitarlos, además de revisar sus entregas y reintentar una. La URL base es `https://api-sandbox.mynexusapi.com` en pruebas y `https://api.mynexusapi.com` en producción. Las operaciones que envían un cuerpo usan `Content-Type: application/json`. | Método y ruta | Para qué | Scope | |---|---|---| | `GET /v1/webhooks/destinos` | Lista los destinos que puede ver la llave | `webhooks:leer` | | `GET /v1/webhooks/destinos/{id}` | Consulta un destino | `webhooks:leer` | | `POST /v1/webhooks/destinos` | Crea un destino y devuelve el secreto una vez | `webhooks:gestionar` | | `PUT /v1/webhooks/destinos/{id}/eventos` | Reemplaza los eventos suscritos | `webhooks:gestionar` | | `POST /v1/webhooks/destinos/{id}/rotar-secreto` | Rota el secreto y lo devuelve una vez | `webhooks:gestionar` | | `POST /v1/webhooks/destinos/{id}/probar` | Envía el evento de prueba | `webhooks:probar` | | `POST /v1/webhooks/destinos/{id}/pausar` | Pausa las entregas nuevas | `webhooks:gestionar` | | `POST /v1/webhooks/destinos/{id}/reanudar` | Reactiva el destino | `webhooks:gestionar` | | `POST /v1/webhooks/destinos/{id}/deshabilitar` | Da de baja el destino | `webhooks:gestionar` | | `GET /v1/webhooks/destinos/{id}/entregas` | Lista las últimas 50 entregas | `webhooks:leer` | | `GET /v1/webhooks/destinos/{id}/entregas/{entregaId}/intentos` | Lista los intentos de una entrega | `webhooks:leer` | | `POST /v1/webhooks/destinos/{id}/entregas/{eventoId}/reintentar` | Reenvía un evento ahora | `webhooks:reintentar` | La columna **Scope** aplica a los agentes que se conectan con OAuth, como los de nuestro [servidor MCP](/v1/guias/mcp), que solo pueden usar las operaciones cuyo scope les concediste. Una API Key no necesita scopes: con ella puedes usar las doce operaciones sobre los destinos de los RUC que tiene permitidos. ### Parámetros de ruta | Parámetro | Tipo | Obligatorio | Descripción | |---|---|---|---| | `id` | UUID | Sí, salvo al listar y al crear | El `publicId` del destino, tal como lo devuelven la creación y el listado. | | `entregaId` | UUID | Sí, al listar intentos | El `publicId` de la entrega, tal como lo devuelve el listado de entregas. | | `eventoId` | UUID | Sí, al reintentar | El `eventId` de la entrega, tal como lo devuelve el listado de entregas. Identifica el evento que se reenvía. | ### Crear un destino El cuerpo para crear un destino es: ```json { "url": "https://erp.tu-empresa.com/webhooks/ecuafact", "eventos": ["document.authorized", "document.rejected", "document.failed"], "ruc": "0123456789001" } ``` | Campo | Tipo | Obligatorio | Descripción | |---|---|---|---| | `url` | string | Sí | URL HTTPS de tu endpoint, de hasta 2048 caracteres y sin espacios. Debe cumplir los [requisitos de la URL](#requisitos-de-la-url). | | `eventos` | arreglo de string | Sí | Al menos uno de `document.authorized`, `document.rejected`, `document.failed` y `operation.requires_attention`. Los repetidos se ignoran. | | `ruc` | string | No | RUC de 13 dígitos. Si lo omites, el destino recibe los eventos de todos los RUC. | Si envías `ruc`, el destino solo recibe los eventos de ese contribuyente. Una API Key limitada a uno o varios RUC no puede crear un destino para todos ni para un RUC que no tenga permitido. La respuesta incluye `ruc` para que puedas distinguir ambos casos. La respuesta es un `201 Created` con la cabecera `Location` del destino: ```json { "publicId": "3f2b8c1e-5a47-4d0e-9b61-0c7d2e8f1a90", "url": "https://erp.tu-empresa.com/webhooks/ecuafact", "secretoUnaVez": "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=", "ruc": "0123456789001" } ``` | Campo | Tipo | Descripción | |---|---|---| | `publicId` | string (UUID) | Identificador del destino, el `id` de las demás operaciones. | | `url` | string | URL registrada. | | `secretoUnaVez` | string | Secreto de firma. Solo se muestra en esta respuesta y en la rotación. | | `ruc` | string o `null` | RUC del destino, o `null` si recibe todos. | La rotación del secreto devuelve esta misma forma, con el secreto nuevo en `secretoUnaVez`. El secreto se muestra **una sola vez**, en la respuesta de creación o de rotación, así que guárdalo en cuanto lo recibas. ### Consultar y listar destinos `GET /v1/webhooks/destinos` devuelve un arreglo con los destinos de tu integración que tu API Key puede ver, y `GET /v1/webhooks/destinos/{id}` devuelve uno solo. Un destino deshabilitado no aparece en el listado y su consulta responde 404. ```json { "publicId": "3f2b8c1e-5a47-4d0e-9b61-0c7d2e8f1a90", "url": "https://erp.tu-empresa.com/webhooks/ecuafact", "state": "active", "fallosConsecutivos": 0, "ultimoFallo": null, "creado": "2026-11-13T15:04:05.123Z", "eventos": ["document.authorized", "document.rejected", "document.failed"], "ruc": "0123456789001" } ``` | Campo | Tipo | Descripción | |---|---|---| | `publicId` | string (UUID) | Identificador del destino. | | `url` | string | URL registrada. | | `state` | string | `active` si recibe eventos, o `paused` si está pausado, por ti o por fallos consecutivos. | | `fallosConsecutivos` | integer | Fallos seguidos que cuentan para la pausa automática. Un 2xx lo reinicia. | | `ultimoFallo` | string o `null` | Fecha y hora del último fallo, en UTC. | | `creado` | string | Fecha y hora de creación, en UTC. | | `eventos` | arreglo de string | Eventos a los que está suscrito. | | `ruc` | string o `null` | RUC del destino, o `null` si recibe todos. | ### Cambiar los eventos de un destino `PUT /v1/webhooks/destinos/{id}/eventos` reemplaza la lista completa de eventos. Envía todos los que quieres recibir, no solo los nuevos. ```json { "eventos": ["document.authorized", "document.failed"] } ``` La operación responde 204 sin cuerpo. Con una lista vacía o con un evento que no existe, responde 400. ### Probar, pausar, reanudar, deshabilitar y reintentar Las operaciones `probar` y `reintentar` responden 202 sin cuerpo, porque la entrega ocurre después; revisa su resultado en las entregas del destino. Las operaciones `pausar`, `reanudar` y `deshabilitar` responden 204 sin cuerpo. Pausar detiene los eventos nuevos, reanudar reinicia el contador de fallos y deshabilitar da de baja el destino de forma definitiva. El efecto de cada una es el de la acción del portal con el mismo nombre, que se describe en [Acciones del portal](#acciones-del-portal). Las entregas, los reintentos y el reenvío siguen las reglas de [Entrega](#entrega) y de [Reintentos](#reintentos-y-que-se-considera-fallo). El evento de prueba conserva `probe` en `"true"` y, si el destino es de un RUC, incluye ese `ruc`. ### Entregas e intentos `GET /v1/webhooks/destinos/{id}/entregas` devuelve las últimas 50 entregas del destino. ```json [ { "publicId": "8a1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "eventId": "5b6c7d8e-9f01-4a2b-8c3d-4e5f6a7b8c9d", "intento": 1, "estado": "sent", "programado": "2026-11-13T15:04:05Z", "enviado": "2026-11-13T15:04:06Z", "httpStatus": 200, "codigoError": null, "tipoEvento": "document.authorized" } ] ``` | Campo | Tipo | Descripción | |---|---|---| | `publicId` | string (UUID) | Identificador de la entrega, el `entregaId` de los intentos. | | `eventId` | string (UUID) | Identificador del evento, el `eventoId` del reintento. Es el mismo valor que viaja en `webhook-id`. | | `intento` | integer | Número del intento de esta entrega. | | `estado` | string | `pending` espera su envío, `leased` se está enviando, `sent` se entregó, `failed` falló y se reintentará, `rejected` la rechazó tu servidor y `dead` agotó los intentos. Corresponden a los estados que el portal muestra en [Estados de una entrega](#estados-de-una-entrega). | | `programado` | string | Fecha y hora, en UTC, para la que se programó el envío. | | `enviado` | string o `null` | Fecha y hora del envío, en UTC. | | `httpStatus` | integer o `null` | Código HTTP que respondió tu servidor. `null` si no hubo respuesta. | | `codigoError` | string o `null` | `error_servicio` cuando hubo un error y `null` si no. La causa exacta está en los intentos. | | `tipoEvento` | string | Tipo del evento entregado. | `GET /v1/webhooks/destinos/{id}/entregas/{entregaId}/intentos` devuelve hasta 20 intentos de una entrega. ```json [ { "intento": 1, "fecha": "2026-11-13T15:04:06Z", "httpStatus": 503, "codigoError": null, "duracionMs": 412, "resultado": "retry" } ] ``` | Campo | Tipo | Descripción | |---|---|---| | `intento` | integer | Número del intento. | | `fecha` | string | Fecha y hora del intento, en UTC. | | `httpStatus` | integer o `null` | Código HTTP que respondió tu servidor. `null` si no hubo respuesta. | | `codigoError` | string o `null` | Causa cuando no hubo respuesta HTTP: `webhook_timeout`, `webhook_dns`, `webhook_conexion`, `webhook_tls` o `webhook_transporte`. Cualquier otro error del envío se informa como `error_servicio`. | | `duracionMs` | integer o `null` | Duración del intento en milisegundos. | | `resultado` | string | `delivered` si tu servidor respondió 2xx, `retry` si falló y se reintentará, `rejected` si tu servidor rechazó la entrega y `dead` si agotó los intentos. | ### Administrar destinos desde el CLI El grupo `ecuafact webhooks destinos` usa la API Key del perfil y el entorno actuales, así que no necesitas una sesión del portal. Cada subcomando indica su método y su ruta, y respeta los mismos scopes de la tabla anterior. ```bash # Lista los destinos que puede ver la llave y consulta uno. ecuafact webhooks destinos listar --entorno sandbox ecuafact webhooks destinos ver --entorno sandbox # Crea un destino para todos los RUC con los cuatro eventos. ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact --entorno sandbox # Crea un destino limitado a un RUC y a dos eventos. ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact \ --eventos document.authorized,document.failed --ruc 0123456789001 --entorno sandbox # Reemplaza los eventos suscritos de un destino. ecuafact webhooks destinos eventos --eventos document.authorized,document.failed --entorno sandbox # Pide a la plataforma que envíe el evento de prueba a un destino. ecuafact webhooks destinos probar-destino --entorno sandbox # Pausa, reanuda, rota el secreto o da de baja el destino. ecuafact webhooks destinos pausar --entorno sandbox ecuafact webhooks destinos reanudar --entorno sandbox ecuafact webhooks destinos rotar --entorno sandbox ecuafact webhooks destinos deshabilitar --entorno sandbox # Consulta las últimas 50 entregas, los intentos de una y reenvía un evento. ecuafact webhooks destinos entregas --entorno sandbox ecuafact webhooks destinos intentos --entorno sandbox ecuafact webhooks destinos reintentar --entorno sandbox ``` `crear` y `rotar` devuelven el secreto una sola vez. En la salida de tabla se muestra; con `--salida json` o `--salida csv` solo aparece si agregas `--mostrar-secreto`. El CLI nunca guarda el secreto en un archivo ni lo escribe en un mensaje. Si usas `--eventos`, sepáralos con coma y elige entre `document.authorized`, `document.rejected`, `document.failed` y `operation.requires_attention`; si lo omites, se suscriben los cuatro. ### Administrar destinos en Postman La colección trae la carpeta **08 · Webhooks** con una petición por operación: `08.1 · Crear destino`, `08.2 · Listar destinos`, `08.3 · Pausar destino`, `08.4 · Reanudar destino`, `08.5 · Rotar secreto`, `08.6 · Entregas`, `08.7 · Reintentar entrega`, `08.8 · Deshabilitar destino`, `08.9 · Consultar destino`, `08.10 · Cambiar eventos del destino`, `08.11 · Probar destino` y `08.12 · Intentos de una entrega`. Usa `{{baseUrl}}` y `{{apiKey}}` del environment, y `{{identificacion}}` en el `ruc` del destino. Al crear un destino, la prueba guarda su `publicId` en `{{idDestino}}`; al listar entregas, guarda el primer `eventId` en `{{eventoId}}` para el reintento. La colección no guarda ni imprime el secreto: cópialo de la respuesta de `08.1` o `08.5` y guárdalo en tu servidor. ### Estados de este endpoint Todas las respuestas de error usan el cuerpo plano con `estado`, `codEstado`, `msgError` y `errores`, como se explica en [Errores](/v1/guias/errores). En las validaciones, `errores` trae el detalle del campo. | `codEstado` | HTTP | Operación | Cuándo ocurre | Qué hacer | |---|---|---|---|---| | - | 200, 201, 202, 204 | Todas | La operación se aceptó: 200 en consultas y rotación, 201 en la creación, 202 en `probar` y `reintentar`, y 204 en el resto. | Usa la respuesta. En la creación y la rotación, guarda `secretoUnaVez`. | | 3003 (`solicitud_invalida`) | 400 | Crear | La `url` falta, no es HTTPS, usa un puerto distinto del 443, trae credenciales, supera 2048 caracteres, no resuelve o apunta a una red no pública. También ocurre si `ruc` no tiene 13 dígitos o si `eventos` está vacío o trae un evento desconocido. | Corrige el campo indicado en `errores`. Los requisitos están en [Requisitos de la URL](#requisitos-de-la-url). | | 3003 (`solicitud_invalida`) | 400 | Reemplazar eventos | `eventos` está vacío o trae un evento desconocido. | Envía al menos uno de los cuatro eventos del contrato. | | 3009 (`credenciales_invalidas`) | 401 | Todas | La API Key falta o no es válida. | Revisa la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | Todas | La IP no está permitida o no se pudo identificar. | Registra tu IP en **Cuenta > IP permitidas**. | | 3011 (`acceso_denegado`) | 403 | Crear | Tu API Key no tiene alcance para el `ruc` indicado, o para todos los RUC cuando lo omites. | Usa un RUC de [`/v1/contexto`](/v1/guias/consulta-contexto) o una API Key con alcance para todos los RUC. | | 3011 (`acceso_denegado`) | 403 | Todas | Un agente conectado con OAuth no tiene concedido el scope de la operación. | Concede al agente el scope de la tabla de operaciones. | | 3013 (`no_encontrado`) | 404 | Las que reciben `{id}` | El destino no existe, está deshabilitado o pertenece a un RUC que tu API Key no puede ver. | Verifica el `id` con el listado de destinos. | | 3003 (`solicitud_invalida`) | 400 | Crear, reanudar | En el ambiente de pruebas ya tienes 10 destinos sin deshabilitar. `errores` lo indica. | Deshabilita uno de los destinos que ya no uses. | | 3006 (`cuerpo_excedido`) | 413 | Crear, reemplazar eventos | El cuerpo supera el tamaño permitido. | Envía un cuerpo más pequeño. | | sin cuerpo | 415 | Crear, reemplazar eventos | El `Content-Type` no es `application/json`. | Envía el `Content-Type` correcto. | | 5005 (`limite_solicitudes`) | 429 | Todas | Superaste el límite de solicitudes. | Espera los segundos que indica `Retry-After` y reintenta. | ## Entrega Cada entrega es una petición HTTP con estas características. | Elemento | Valor | |---|---| | Método | `POST` a la URL del destino. | | `Content-Type` | `application/json; charset=utf-8` | | `Ecuafact-Signature` | `t=,v1=`. Cómo verificarla: [Verificación de firma](/v1/guias/webhooks-firma). | | `webhook-id`, `webhook-timestamp` y `webhook-signature` | La misma entrega firmada según el estándar abierto Standard Webhooks, que puedes verificar con sus librerías oficiales en lugar de `Ecuafact-Signature`. `webhook-id` es el mismo en todos los reintentos y reenvíos del evento. Cómo verificarlas: [Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks). | | Cuerpo | Objeto JSON compacto, sin espacios ni saltos de línea, codificado en UTF-8. | | Tiempo de espera | 15 segundos. Si tu servidor no termina de responder en ese tiempo, la entrega cuenta como fallo y se reintenta. | | Éxito | Cualquier código 2xx. El cuerpo de tu respuesta se ignora. | | Fallo que se reintenta | La falta de respuesta (tiempo de espera agotado, dominio que no resuelve, conexión rechazada o error TLS), un 408, un 429 o cualquier 5xx. | | Rechazo de tu servidor | Cualquier otro 4xx o un 3xx. Es final y no se reintenta; el detalle está en [Reintentos y qué se considera fallo](#reintentos-y-que-se-considera-fallo). | ## Eventos Te enviamos tres tipos de evento con el resultado final de una emisión, uno por cada clase de resultado, y un aviso cuando un comprobante necesita tu atención antes de tener resultado. El `eventType` te dice de qué se trata, y los campos `estado` y `codEstado` del cuerpo te dicen exactamente qué pasó. | `eventType` | En el portal | Cuándo ocurre | `estado` y `codEstado` en el cuerpo | |---|---|---|---| | `document.authorized` | Documento autorizado | El SRI autorizó el comprobante. | `autorizado`, 2001 | | `document.rejected` | Documento rechazado | El SRI rechazó el comprobante (rechazo fiscal). | `rechazado` con 3001, o `rechazo_configuracion` con 4002 si la firma electrónica del emisor no se acepta | | `document.failed` | Documento no emitido | El comprobante no se emitió: no cumplió una regla de la validación fiscal, falta o está mal una configuración del emisor, o algo impidió definitivamente su autorización. | `rechazado` con 3002, `rechazo_configuracion` con 4001 a 4004, o `error` con 5001, 5006 o 5007 | | `operation.requires_attention` | Operación requiere atención | Todavía no tenemos el resultado del comprobante y no pudimos confirmarlo a tiempo. Es un aviso, no un resultado final. | `recibido`, 1001 o 1002 | Los tres eventos `document.*` traen un estado final, con los mismos valores del [seguimiento](/v1/guias/consulta-operacion#valores-de-estado). Decide siempre con `estado` y `codEstado`, y no solo con `eventType`. En cambio, `operation.requires_attention` no es final: el comprobante sigue `recibido`, con el `codEstado` 1001 o 1002 según ya tenga clave de acceso, y el motivo del aviso llega en `errores`. Cuando tengamos su resultado, te llega el evento `document.*` que corresponda de la misma operación. El mismo `eventType` es también el del [evento de prueba](#evento-de-prueba) que envía el botón **Probar** solo al destino probado; lo distingues porque trae `probe` en `"true"`. Una operación que termina en `cancelado` no genera evento. Si una emisión lleva más tiempo del esperado sin que te llegue ningún evento, consulta su estado en el seguimiento. Si recibes un `eventType` que tu sistema no reconoce, responde un 2xx e ignóralo; así un tipo de evento que no procesas no acumula fallos ni pausa tu destino. ### Campos del cuerpo Los valores del cuerpo son **cadenas de texto**, incluso las fechas, salvo `codEstado`, que es un número entero, y `errores`, que es un arreglo de textos. El orden de las claves no está garantizado, así que lee cada campo por su nombre y no rechaces el evento si trae un campo que tu sistema no reconoce. | Campo | Tipo | Presente en | Descripción | |---|---|---|---| | `eventType` | string | Todos | Tipo de evento (tabla anterior). | | `resourceId` | string (UUID) | Todos | Recurso del evento. En los eventos `document.*` y en el aviso `operation.requires_attention` es el `idOperacion`. En el evento de prueba es el identificador del destino. | | `occurredAtUtc` | string | Todos | Momento en que se registró el evento, en UTC e ISO 8601 con 7 decimales (`2026-10-07T15:04:05.1234567Z`). No cambia en los reintentos. | | `idOperacion` | string (UUID) | `document.*` y aviso | Identificador de la [operación](/v1/guias/glosario) que devolvió la emisión. Úsalo para ubicar el comprobante en tu sistema. | | `estado` | string | `document.*` y aviso | En los eventos `document.*`, el estado final de la operación: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`. En el aviso, `recibido`. Son los mismos valores del seguimiento. | | `tipoDocumento` | string | `document.*` y aviso | Tipo de comprobante: `01`, `03`, `04`, `05`, `06` o `07`. | | `ruc` | string | `document.*` y aviso | Identificación del contribuyente emisor, la misma `identificacion` de la ruta y de `infoTributaria.ruc`. Te permite enrutar un destino compartido por varios RUC. | | `claveAcceso` | string | `document.authorized`, `document.rejected`; en `document.failed` y en el aviso, solo si ya se había asignado | [Clave de acceso](/v1/guias/glosario) de 49 dígitos. | | `fhAutorizacion` | string | `document.authorized` | Fecha y hora de autorización, en ISO 8601 con zona horaria, igual a la del seguimiento. | | `codEstado` | integer | `document.*` y aviso | Código de resultado de 4 dígitos del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), por ejemplo 2001 en una autorización, 3001 en un rechazo del SRI o 4002 si la firma no es válida; en el aviso, 1001 o 1002. Su primer dígito coincide con el `estado`. Cada valor y qué hacer ante él están en [Qué hacer ante cada evento](#que-hacer-ante-cada-evento) y en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion). Trata un valor que no reconozcas según su primer dígito y como un problema que debes revisar. | | `msgError` | string | `document.rejected` y `document.failed` | Descripción fija del código, en español. No viene cuando no hay error, es decir, en `document.authorized` ni en el aviso. Muéstralo o regístralo, pero no lo compares en tu código. | | `errores` | array de string | `document.*` y aviso | Detalle específico del resultado, por ejemplo el mensaje del SRI en un rechazo fiscal o el campo que no cumplió una validación. En el aviso trae el motivo. Viene siempre y es `[]` cuando no hay detalle. Muéstralo o regístralo, pero no lo compares en tu código. | | `probe` | string | Evento de prueba | Siempre `"true"`. | ### document.authorized ```json { "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "estado": "autorizado", "codEstado": 2001, "errores": [], "tipoDocumento": "01", "ruc": "0123456789001", "claveAcceso": "0710202601012345678900110010010000001231234567811", "fhAutorizacion": "2026-10-07T10:04:05-05:00", "eventType": "document.authorized", "resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "occurredAtUtc": "2026-10-07T15:04:05.1234567Z" } ``` ### document.rejected ```json { "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "estado": "rechazado", "tipoDocumento": "01", "claveAcceso": "0710202601012345678900110010010000001231234567811", "codEstado": 3001, "msgError": "El SRI rechazó el comprobante.", "errores": [ "CLAVE ACCESO REGISTRADA" ], "eventType": "document.rejected", "resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "occurredAtUtc": "2026-10-07T15:04:05.1234567Z" } ``` ### document.failed ```json { "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "estado": "rechazo_configuracion", "tipoDocumento": "01", "codEstado": 4002, "msgError": "La firma electrónica no es válida.", "errores": [], "eventType": "document.failed", "resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "occurredAtUtc": "2026-10-07T15:04:05.1234567Z" } ``` Los ejemplos se muestran indentados para leerlos. El cuerpo real llega en una sola línea y la firma se calcula sobre esos bytes exactos. ### operation.requires_attention ```json { "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "estado": "recibido", "tipoDocumento": "01", "codEstado": 1001, "errores": [ "Aun no se confirma el resultado del comprobante; se sigue consultando." ], "eventType": "operation.requires_attention", "resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "occurredAtUtc": "2026-10-07T15:04:05.1234567Z" } ``` ### Evento de prueba Al pulsar **Probar** en el portal, el destino recibe este evento aunque no esté suscrito a él. Sirve para comprobar la conexión y la firma, y no corresponde a ningún comprobante. ```json { "probe": "true", "eventType": "operation.requires_attention", "resourceId": "9b2e4f60-1c3d-4e5f-8a7b-6c5d4e3f2a1b", "occurredAtUtc": "2026-10-07T15:04:05.1234567Z" } ``` Tu servidor solo tiene que responder un 2xx. El evento de prueba se registra una vez por destino, así que si **Probar** no genera una entrega nueva en **Entregas**, usa **Reenviar** sobre la entrega de prueba que ya existe. ### Qué hacer ante cada evento Cada combinación de `estado` y `codEstado` pide una acción distinta. En la tabla, "claves nuevas" significa una `Idempotency-Key` nueva y una `referenciaExterna` nueva. | Evento | `estado` | `codEstado` | Qué pasó | Qué hacer | |---|---|---|---|---| | `document.authorized` | `autorizado` | 2001 | El SRI autorizó el comprobante. | Marca el comprobante como autorizado en tu sistema, guarda `claveAcceso` y descarga el [RIDE](/v1/guias/consulta-ride) y el [XML](/v1/guias/consulta-xml) si los necesitas. | | `document.rejected` | `rechazado` | 3001 (`rechazo_sri`) | Es un rechazo fiscal: el SRI no aceptó el comprobante, y `errores` trae su mensaje. | Corrige el comprobante según `errores` y la guía de su tipo, y emítelo como un comprobante nuevo, con un `secuencial` **nuevo** (u omítelo para que te asignemos el siguiente) y claves nuevas. El número rechazado por el SRI no se puede reutilizar; si lo intentas, la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`). | | `document.failed` | `rechazado` | 3002 (`comprobante_invalido`) | La validación fiscal rechazó el contenido del comprobante antes de enviarlo al SRI. `errores` trae el detalle por campo cuando existe. | Corrige el comprobante y emítelo de nuevo con el mismo número y claves nuevas. | | `document.failed` | `rechazo_configuracion` | 4001 (`emisor_no_configurado`) | Al emisor le falta configuración para emitir ante el SRI. | Revisa el RUC en **Cuenta > Contribuyentes** del Portal del Cliente: en el ambiente en que emitiste, la columna **Pruebas** o **Producción** debe mostrar **Listo** o **En producción**. Si muestra **Configurando**, espera a que termine; si ya está listo, escribe a soporte con el `idOperacion`. Después emite de nuevo con el mismo número y claves nuevas. | | `document.rejected` o `document.failed` | `rechazo_configuracion` | 4002 (`firma_no_valida`) | La firma electrónica del emisor está caducada o no es válida. | En **Cuenta > Contribuyentes** del Portal del Cliente, pulsa **Reemplazar firma** en la fila del RUC y carga una firma electrónica vigente; si tu portal no muestra esa opción, cárgala en **Cuenta > Certificados** con **Reemplazar certificado**. Después emite de nuevo con el mismo número y claves nuevas. | | `document.failed` | `rechazo_configuracion` | 4003 (`suscripcion_inactiva`) | La suscripción del emisor no está activa. | Regulariza la suscripción y emite de nuevo con el mismo número y claves nuevas. | | `document.failed` | `rechazo_configuracion` | 4004 (`cupo_agotado`) | No quedan documentos en tus paquetes vigentes. | Compra un paquete y emite de nuevo con el mismo número y claves nuevas. | | `document.failed` | `error` | 5006 (`entrega_no_posible`) | El comprobante no se pudo emitir y confirmamos que no se creó. | Emite de nuevo el mismo comprobante con el mismo número y claves nuevas. | | `document.failed` | `error` | 5007 (`resultado_no_confirmado`) | No pudimos confirmar si el comprobante llegó a crearse. | **No emitas de nuevo**, porque podrías duplicarlo. Búscalo en el seguimiento y escribe a soporte con el `idOperacion`. | | `document.failed` | `error` | 5001 (`error_interno`) | Tuvimos un fallo inesperado y el comprobante no se completó. | Escribe a soporte con el `idOperacion` antes de emitir de nuevo. | | `operation.requires_attention` | `recibido` | 1001 o 1002 | Todavía no tenemos el resultado del comprobante y no pudimos confirmarlo a tiempo; `errores` trae el motivo. Es un aviso, no un resultado final. | **No emitas de nuevo**, porque podrías duplicarlo. Espera el evento `document.*` de la misma operación o consulta el [seguimiento](/v1/guias/consulta-operacion); si el aviso se prolonga, escribe a soporte con el `idOperacion`. | | `operation.requires_attention` con `probe` en `"true"` | - | - | Es el evento de prueba del portal. | Responde un 2xx. | Una operación `cancelado`, con el `codEstado` 6001 (`operacion_cancelada`), no genera evento. La ves en el [seguimiento](/v1/guias/consulta-operacion): el comprobante no se emitió ni consumió cupo, y puedes emitirlo de nuevo con claves nuevas y el mismo número. Varias filas de la tabla piden **emitir de nuevo con el mismo número**. Para hacerlo, envía la Estructura del comprobante corregida con el mismo `estab`, `ptoEmi` y `secuencial` de la operación anterior. Si enviaste el `secuencial` al emitir, ya lo tienes en tu sistema; si dejaste que te lo asignáramos, lo encuentras en el `numeroDocumento` del [seguimiento](/v1/guias/consulta-operacion) o dentro de la `claveAcceso`, cuando el evento la trae. Usa siempre claves nuevas, porque con las anteriores la API te devuelve la operación original y no emite, o responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). La API acepta ese envío con un 202 y puede **reutilizar la misma operación**: la respuesta trae el mismo `idOperacion` y no usa otro documento de tu cupo. Como generamos como máximo un evento de cada `eventType` por operación, confirma después el resultado con el [seguimiento](/v1/guias/consulta-operacion). Si el reenvío termina en el mismo tipo de evento que ya recibiste, no te llega un evento nuevo. En resumen, un `rechazado` y un `rechazo_configuracion` exigen **corregir** la causa antes de emitir de nuevo. Un `error` con 5006 y un `cancelado` con 6001 solo piden volver a emitir. En cambio, un `error` con 5007 o 5001 es una **notificación** que exige no emitir de nuevo hasta confirmar con soporte qué pasó. ## Reintentos y qué se considera fallo Cada entrega espera una respuesta 2xx de tu servidor en 15 segundos como máximo, y no sigue redirecciones. Lo que hacemos después depende de lo que responda tu servidor. | Respuesta de tu servidor | Qué hacemos | Cuenta para pausar el destino | Qué hacer | |---|---|---|---| | 2xx | Damos la entrega por completada. | No; reinicia el contador | No hagas nada. | | Sin respuesta: tiempo agotado, dominio que no resuelve, conexión rechazada o error TLS | Reintentamos. | Sí | Revisa que tu endpoint esté en línea, con DNS y certificado válidos, y que responda en menos de 15 segundos. | | 408, 429, 500, 502, 503, 504 y cualquier otro 5xx | Reintentamos. Si envías `Retry-After`, esperamos al menos ese tiempo, con un máximo de 60 minutos. | Sí | Responde un 2xx en cuanto guardes el evento y procésalo después. | | Otro 4xx (400, 401, 403, 404, 410, 422...) o un 3xx | La entrega queda **rechazada por tu servidor** y no reintentamos. | No | Corrige tu endpoint (ruta, autenticación, validación de la firma) y usa **Reenviar** en el portal. | Ante un fallo temporal de tu lado, como una base de datos caída o un despliegue en curso, responde 503 con `Retry-After` y no un 4xx. Un 4xx deja la entrega rechazada y tendrías que reenviarla a mano desde el portal. Reintentamos cada entrega fallida hasta 8 intentos en total, con esperas cada vez más largas que, sumadas, se extienden por varios días. Así, una caída de tu servidor de un fin de semana no te hace perder eventos. Cada entrega muestra su número de intento en **Entregas**, y el historial de cada intento está en **Intentos**. - Si los 8 intentos fallan, la entrega queda en estado **Agotado** y ya no hay más reintentos automáticos. Puedes forzar un envío con **Reenviar** desde **Entregas**. - **Reenviar** crea una entrega nueva que continúa la numeración de intentos de ese evento en el destino. Si el evento ya llegó al intento 8, el reenvío es un solo intento y, si falla, queda **Agotado** sin reintentos automáticos. - Una entrega **rechazada por tu servidor** también es final. Corrige tu endpoint y usa **Reenviar**. - Cada reintento lleva el **mismo cuerpo**, con el mismo `occurredAtUtc` y el mismo `webhook-id`, y una firma nueva, con un `t` y un `webhook-timestamp` nuevos. - **Pausa del destino.** Tras **8 fallos consecutivos que cuentan**, es decir, sin respuesta o con 408, 429 o 5xx, sumando todos los eventos del destino, el destino pasa a **Pausado** y el portal muestra "Entrega pausada". Los rechazos de tu servidor (3xx y otros 4xx) no cuentan. Un 2xx posterior reinicia el contador de fallos, pero **no** reanuda el destino; para eso, pulsa **Reanudar**. > [!WARNING] > Mientras un destino está pausado, los eventos nuevos **no se le entregan ni > quedan en espera**. Al reanudarlo, solo recibirás los eventos que ocurran desde > ese momento. Por eso, después de una pausa, revisa con el > [seguimiento](/v1/guias/consulta-operacion) las operaciones que quedaron sin > resultado en tu sistema. ### Estados de una entrega En **Integración > Eventos > Entregas** ves, para cada entrega, la fecha en hora de Ecuador, el evento, el estado, el número de intento y el código HTTP. | Estado en el portal | Qué significa | Qué hacer | |---|---|---| | **Pendiente** | La entrega espera su primer intento o el siguiente reintento. | No hagas nada. | | **Enviando** | Estamos enviando la entrega en este momento. | No hagas nada. | | **Fallido** | El intento falló y programamos un reintento. | Revisa la causa en **Intentos** y corrige tu endpoint si hace falta. | | **Entregado** | Tu servidor respondió un 2xx. | No hagas nada. | | **Rechazado por tu servidor (HTTP xxx)** | Tu servidor respondió un 3xx u otro 4xx. Es un estado final. | Corrige tu endpoint y usa **Reenviar**. | | **Agotado** | Fallaron todos los intentos, sin respuesta o con 408, 429 o 5xx. Es un estado final. | Corrige la causa y usa **Reenviar**. | Con **Intentos** ves el historial de esa entrega: la fecha, el número de intento, el resultado (**Entregado**, **Fallido, se reintenta**, **Agotado** o **Rechazado por tu servidor**), el código HTTP, la causa del error y la duración en milisegundos. Cuando no hubo respuesta HTTP, la columna de error dice cuál fue la causa: | Causa | Qué pasó | Qué hacer | |---|---|---| | Tiempo de espera agotado | Tu servidor no terminó de responder en 15 segundos. | Responde un 2xx en cuanto guardes el evento y procésalo después. | | El dominio no resuelve | El nombre de tu URL no tiene registro DNS válido. | Revisa el DNS de tu dominio. | | Conexión rechazada | No se pudo abrir la conexión con tu servidor, por un puerto cerrado, un firewall o un servidor apagado. | Revisa que tu servidor escuche en el puerto 443 y acepte conexiones externas. | | Error TLS | Falló la conexión segura, por un certificado vencido, autofirmado o sin la cadena completa. | Instala un certificado válido emitido por una autoridad reconocida, con su cadena completa. | | Error de red | Ocurrió otro error de red durante el envío. | Revisa la conectividad de tu servidor; nosotros reintentamos. | ## Garantías y deduplicación Te damos tres garantías sobre la entrega de eventos, y tu servidor debe estar preparado para cada una: - **Al menos una vez.** Un mismo evento puede llegarte más de una vez, por un reintento porque tu servidor respondió tarde o por un **Reenviar** manual. - **Sin orden garantizado.** Los eventos de operaciones distintas pueden llegar en cualquier orden. Para conocer el estado actual de una operación, consulta el seguimiento en lugar de asumir que el último evento recibido es el vigente. - **Un evento por tipo y operación.** Generamos como máximo un evento de cada `eventType` por operación. Una misma operación sí puede recibir dos eventos distintos, por ejemplo un `document.failed` con 3002 y, después de que reenvías el comprobante corregido con el mismo número, un `document.authorized` o un `document.rejected`. Como un evento puede repetirse, descarta los duplicados con esta clave única: | Clave única | Por qué | |---|---| | `eventType` + `resourceId` | Identifica un evento. Sus repeticiones (reintentos y reenvíos) traen el mismo valor, mientras `t` y la firma cambian. | | Caso | `eventType` + `resourceId` | Qué hacer | |---|---|---| | Reintento o **Reenviar** del mismo evento | Es igual al ya guardado. | Responde un 2xx sin volver a procesar. | | `document.failed` y, tras reenviar con el mismo número, `document.authorized` de la misma operación | Es distinto, porque cambia `eventType`. | Procesa ambos. El evento más reciente refleja el estado vigente; si dudas, confírmalo en el seguimiento. | | Eventos de operaciones distintas | Es distinto, porque cambia `resourceId`. | Procesa cada uno. | Una forma simple de aplicarlo es una tabla con clave primaria compuesta. Inserta el evento y aplica su efecto en la misma transacción; si el `INSERT` choca con la clave, el evento es un duplicado. ```sql CREATE TABLE webhook_evento ( event_type VARCHAR(80) NOT NULL, resource_id CHAR(36) NOT NULL, recibido_en TIMESTAMP NOT NULL, cuerpo TEXT NOT NULL, PRIMARY KEY (event_type, resource_id) ); ``` ## Implementación en tu servidor Los ejemplos de esta sección son un endpoint completo que puedes copiar y ejecutar. Todos hacen lo mismo, en este orden: 1. Leen el **cuerpo crudo**, es decir, los bytes tal como llegaron, sin deserializarlo. 2. Verifican la cabecera `Ecuafact-Signature` con tu secreto. Si la firma no es válida, responden 401. 3. Solo entonces interpretan el JSON. 4. Descartan los duplicados por `eventType` + `resourceId`. 5. Actúan según el evento y responden 200. Si su propio guardado falla, responden 500 para que reintentemos la entrega. Para que puedas ejecutarlos tal cual, los ejemplos guardan los eventos procesados en memoria; en producción, usa la tabla de la sección anterior. Si tu procesamiento tarda, guarda el evento, responde 200 y procesa en segundo plano, porque el tiempo de espera es de 15 segundos. Las pestañas SDK hacen lo mismo con el verificador de firma de cada SDK oficial. > [!WARNING] > Verifica la firma sobre el **cuerpo crudo**. Si tu framework deserializa el > JSON y lo vuelves a serializar, cambian los espacios, el orden o los escapes, y > la firma no coincide. Por eso, no uses el enlace automático a un objeto > (modelo, DTO o POJO) antes de verificar. ```csharp // Program.cs de un proyecto creado con: dotnet new web // Ejecuta: dotnet run --urls http://localhost:3000 using System.Collections.Concurrent; using System.Security.Cryptography; using System.Text; using System.Text.Json; WebApplication app = WebApplication.CreateBuilder(args).Build(); string secreto = Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET")!; ConcurrentDictionary procesados = new(); // Solo para el ejemplo: usa una tabla con clave unica. app.MapPost("/webhooks/ecuafact", async (HttpRequest request) => { using StreamReader lector = new(request.Body, Encoding.UTF8); string cuerpoCrudo = await lector.ReadToEndAsync(); string cabecera = request.Headers["Ecuafact-Signature"].ToString(); if (!Verificar(secreto, cabecera, cuerpoCrudo, TimeSpan.FromMinutes(5))) { return Results.Unauthorized(); } using JsonDocument documento = JsonDocument.Parse(cuerpoCrudo); JsonElement evento = documento.RootElement; string tipo = Texto(evento, "eventType") ?? ""; string recurso = Texto(evento, "resourceId") ?? ""; if (!procesados.TryAdd(tipo + "|" + recurso, true)) { return Results.Ok(); // Duplicado: ya procesado. } switch (tipo) { case "document.authorized": Console.WriteLine($"Autorizado {Texto(evento, "idOperacion")} clave {Texto(evento, "claveAcceso")}"); break; case "document.rejected": Console.WriteLine($"Rechazado por el SRI {Texto(evento, "idOperacion")} ({Texto(evento, "codEstado")}): {Texto(evento, "errores")}"); break; case "document.failed": Console.WriteLine($"No emitido {Texto(evento, "idOperacion")}: {Texto(evento, "estado")} / {Texto(evento, "codEstado")} - {Texto(evento, "msgError")} {Texto(evento, "errores")}"); break; default: Console.WriteLine($"Evento sin accion: {tipo}"); break; } return Results.Ok(); }); app.Run(); static string? Texto(JsonElement objeto, string nombre) { if (objeto.TryGetProperty(nombre, out JsonElement valor)) { // codEstado es un numero y errores un arreglo: se devuelven como su JSON. return valor.ValueKind == JsonValueKind.String ? valor.GetString() : valor.GetRawText(); } return null; } static bool Verificar(string secreto, string cabecera, string cuerpoCrudo, TimeSpan tolerancia) { string? t = null; string? v1 = null; foreach (string parte in cabecera.Split(',')) { string item = parte.Trim(); if (item.StartsWith("t=", StringComparison.Ordinal)) { t = item.Substring(2); } else if (item.StartsWith("v1=", StringComparison.Ordinal)) { v1 = item.Substring(3); } } if (t == null || v1 == null || !long.TryParse(t, out long unix)) { return false; } if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - unix) > (long)tolerancia.TotalSeconds) { return false; } using HMACSHA256 hmac = new(Encoding.UTF8.GetBytes(secreto)); byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(t + "." + cuerpoCrudo)); string esperado = Convert.ToHexString(hash).ToLowerInvariant(); return CryptographicOperations.FixedTimeEquals( Encoding.ASCII.GetBytes(esperado), Encoding.ASCII.GetBytes(v1.ToLowerInvariant())); } ``` ```python # Guarda como webhook.py. Instala: pip install flask # Ejecuta: flask --app webhook run --port 3000 import hashlib import hmac import json import os import time from flask import Flask, request app = Flask(__name__) SECRETO = os.environ["ECUAFACT_WEBHOOK_SECRET"] procesados = set() # Solo para el ejemplo: usa una tabla con clave unica. def verificar(cabecera, cuerpo_crudo, tolerancia=300): partes = dict(p.strip().split("=", 1) for p in cabecera.split(",") if "=" in p) t, v1 = partes.get("t"), partes.get("v1") if not t or not v1 or not t.isdigit(): return False if abs(int(time.time()) - int(t)) > tolerancia: return False firmado = f"{t}.{cuerpo_crudo}".encode("utf-8") esperado = hmac.new(SECRETO.encode("utf-8"), firmado, hashlib.sha256).hexdigest() return hmac.compare_digest(esperado, v1.lower()) @app.post("/webhooks/ecuafact") def webhook(): cuerpo_crudo = request.get_data(as_text=True) # Cuerpo crudo, sin parsear. if not verificar(request.headers.get("Ecuafact-Signature", ""), cuerpo_crudo): return "", 401 evento = json.loads(cuerpo_crudo) # Solo despues de verificar la firma. clave = (evento.get("eventType"), evento.get("resourceId")) if clave in procesados: return "", 200 # Duplicado: ya procesado. procesados.add(clave) tipo = evento.get("eventType") if tipo == "document.authorized": print("Autorizado", evento["idOperacion"], evento.get("claveAcceso")) elif tipo == "document.rejected": print("Rechazado por el SRI", evento["idOperacion"], evento.get("codEstado"), evento.get("errores")) elif tipo == "document.failed": print("No emitido", evento["idOperacion"], evento.get("estado"), "/", evento.get("codEstado"), "-", evento.get("msgError"), evento.get("errores")) else: print("Evento sin accion:", tipo) return "", 200 ``` ```javascript // Node.js 18 o superior. Instala: npm install express // Guarda como webhook.mjs y ejecuta: node webhook.mjs import express from 'express'; import { createHmac, timingSafeEqual } from 'node:crypto'; const SECRETO = process.env.ECUAFACT_WEBHOOK_SECRET; const procesados = new Set(); // Solo para el ejemplo: usa una tabla con clave unica. const app = express(); app.post('/webhooks/ecuafact', express.raw({ type: 'application/json' }), (req, res) => { const cuerpoCrudo = Buffer.isBuffer(req.body) ? req.body.toString('utf8') : ''; if (!verificar(SECRETO, req.get('Ecuafact-Signature') ?? '', cuerpoCrudo)) { return res.sendStatus(401); } const evento = JSON.parse(cuerpoCrudo); // Solo despues de verificar la firma. const clave = `${evento.eventType}|${evento.resourceId}`; if (procesados.has(clave)) { return res.sendStatus(200); // Duplicado: ya procesado. } procesados.add(clave); switch (evento.eventType) { case 'document.authorized': console.log('Autorizado', evento.idOperacion, evento.claveAcceso); break; case 'document.rejected': console.log('Rechazado por el SRI', evento.idOperacion, evento.codEstado, evento.errores); break; case 'document.failed': console.log('No emitido', evento.idOperacion, evento.estado, '/', evento.codEstado, '-', evento.msgError, evento.errores); break; default: console.log('Evento sin accion:', evento.eventType); } res.sendStatus(200); }); function verificar(secreto, cabecera, cuerpoCrudo, toleranciaSegundos = 300) { let t = null; let v1 = null; for (const parte of cabecera.split(',')) { const item = parte.trim(); if (item.startsWith('t=')) t = item.slice(2); else if (item.startsWith('v1=')) v1 = item.slice(3).toLowerCase(); } if (!t || !v1 || !/^\d+$/.test(t)) return false; if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranciaSegundos) return false; const esperado = createHmac('sha256', secreto).update(`${t}.${cuerpoCrudo}`, 'utf8').digest('hex'); const a = Buffer.from(esperado, 'utf8'); const b = Buffer.from(v1, 'utf8'); return a.length === b.length && timingSafeEqual(a, b); } app.listen(3000, () => console.log('Escuchando en http://localhost:3000/webhooks/ecuafact')); ``` ```php $tolerancia) { return false; } $esperado = hash_hmac('sha256', $t . '.' . $cuerpoCrudo, $secreto); return hash_equals($esperado, strtolower($v1)); } ``` ```java // Spring Boot 3 con spring-boot-starter-web. Escucha en el puerto 8080 por defecto. import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.time.Instant; import java.util.HashMap; import java.util.Map; import java.util.Set; import java.util.concurrent.ConcurrentHashMap; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestHeader; import org.springframework.web.bind.annotation.RestController; @RestController public class WebhookController { private static final ObjectMapper JSON = new ObjectMapper(); private final Set procesados = ConcurrentHashMap.newKeySet(); // Solo para el ejemplo. @PostMapping("/webhooks/ecuafact") public ResponseEntity recibir( @RequestHeader(value = "Ecuafact-Signature", defaultValue = "") String cabecera, @RequestBody byte[] cuerpo) throws Exception { String cuerpoCrudo = new String(cuerpo, StandardCharsets.UTF_8); // Bytes exactos recibidos. if (!verificar(System.getenv("ECUAFACT_WEBHOOK_SECRET"), cabecera, cuerpoCrudo, 300)) { return ResponseEntity.status(401).build(); } JsonNode evento = JSON.readTree(cuerpoCrudo); // Solo despues de verificar la firma. String tipo = evento.path("eventType").asText(); if (!procesados.add(tipo + "|" + evento.path("resourceId").asText())) { return ResponseEntity.ok().build(); // Duplicado: ya procesado. } String idOperacion = evento.path("idOperacion").asText(); switch (tipo) { case "document.authorized" -> System.out.println("Autorizado " + idOperacion + " clave " + evento.path("claveAcceso").asText()); case "document.rejected" -> System.out.println("Rechazado por el SRI " + idOperacion + " (" + evento.path("codEstado").asInt() + "): " + evento.path("errores")); case "document.failed" -> System.out.println("No emitido " + idOperacion + ": " + evento.path("estado").asText() + " / " + evento.path("codEstado").asInt() + " - " + evento.path("msgError").asText() + " " + evento.path("errores")); default -> System.out.println("Evento sin accion: " + tipo); } return ResponseEntity.ok().build(); } static boolean verificar(String secreto, String cabecera, String cuerpoCrudo, long tolerancia) throws Exception { Map partes = new HashMap<>(); for (String p : cabecera.split(",")) { String[] kv = p.trim().split("=", 2); if (kv.length == 2) { partes.put(kv[0], kv[1]); } } String t = partes.get("t"); String v1 = partes.get("v1"); if (t == null || v1 == null || !t.matches("\\d+")) { return false; } if (Math.abs(Instant.now().getEpochSecond() - Long.parseLong(t)) > tolerancia) { return false; } Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(secreto.getBytes(StandardCharsets.UTF_8), "HmacSHA256")); byte[] hash = mac.doFinal((t + "." + cuerpoCrudo).getBytes(StandardCharsets.UTF_8)); StringBuilder hex = new StringBuilder(); for (byte b : hash) { hex.append(String.format("%02x", b)); } return MessageDigest.isEqual( hex.toString().getBytes(StandardCharsets.US_ASCII), v1.toLowerCase().getBytes(StandardCharsets.US_ASCII)); } } ``` ```csharp-sdk // Program.cs de un proyecto creado con: dotnet new web // Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run --urls http://localhost:3000 using System.Collections.Concurrent; using System.Text; using System.Text.Json; using Ecuafact.Sdk.Webhooks; WebApplication app = WebApplication.CreateBuilder(args).Build(); string secreto = Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET")!; ConcurrentDictionary procesados = new(); // Solo para el ejemplo. app.MapPost("/webhooks/ecuafact", async (HttpRequest request) => { using StreamReader lector = new(request.Body, Encoding.UTF8); string cuerpoCrudo = await lector.ReadToEndAsync(); string cabecera = request.Headers["Ecuafact-Signature"].ToString(); if (!WebhookSignature.Verify(secreto, cabecera, cuerpoCrudo, DateTimeOffset.UtcNow, TimeSpan.FromMinutes(5))) { return Results.Unauthorized(); } using JsonDocument documento = JsonDocument.Parse(cuerpoCrudo); JsonElement evento = documento.RootElement; string tipo = evento.GetProperty("eventType").GetString() ?? ""; string recurso = evento.GetProperty("resourceId").GetString() ?? ""; if (!procesados.TryAdd(tipo + "|" + recurso, true)) { return Results.Ok(); } switch (tipo) { case "document.authorized": case "document.rejected": case "document.failed": Console.WriteLine($"{tipo} para la operacion {recurso}"); break; default: Console.WriteLine($"Evento sin accion: {tipo}"); break; } return Results.Ok(); }); app.Run(); ``` ```python-sdk # Guarda como webhook.py. Instala: pip install flask "ecuafact>=1.0.0" # Ejecuta: flask --app webhook run --port 3000 import json import os from ecuafact import verify from flask import Flask, request app = Flask(__name__) SECRETO = os.environ["ECUAFACT_WEBHOOK_SECRET"] procesados = set() # Solo para el ejemplo. @app.post("/webhooks/ecuafact") def webhook(): cuerpo_crudo = request.get_data(as_text=True) if not verify(SECRETO, request.headers.get("Ecuafact-Signature", ""), cuerpo_crudo, tolerance_seconds=300): return "", 401 evento = json.loads(cuerpo_crudo) clave = (evento.get("eventType"), evento.get("resourceId")) if clave in procesados: return "", 200 procesados.add(clave) if evento["eventType"] in ("document.authorized", "document.rejected", "document.failed"): print(evento["eventType"], "para la operacion", evento["resourceId"]) else: print("Evento sin accion:", evento["eventType"]) return "", 200 ``` ```javascript-sdk // Node.js 18 o superior. Instala: npm install express @ecuafact/sdk // Guarda como webhook.mjs y ejecuta: node webhook.mjs import express from "express"; import { verify } from "@ecuafact/sdk"; const SECRETO = process.env.ECUAFACT_WEBHOOK_SECRET; const procesados = new Set(); // Solo para el ejemplo. const app = express(); app.post("/webhooks/ecuafact", express.raw({ type: "application/json" }), (req, res) => { const cuerpoCrudo = Buffer.isBuffer(req.body) ? req.body.toString("utf8") : ""; if (!verify(SECRETO, req.get("Ecuafact-Signature") ?? "", cuerpoCrudo, new Date(), 300)) { return res.sendStatus(401); } const evento = JSON.parse(cuerpoCrudo); const clave = `${evento.eventType}|${evento.resourceId}`; if (procesados.has(clave)) return res.sendStatus(200); procesados.add(clave); switch (evento.eventType) { case "document.authorized": case "document.rejected": case "document.failed": console.log(evento.eventType, "para la operacion", evento.resourceId); break; default: console.log("Evento sin accion:", evento.eventType); } res.sendStatus(200); }); app.listen(3000); ``` ```php-sdk procesados = ConcurrentHashMap.newKeySet(); // Solo para el ejemplo. @PostMapping("/webhooks/ecuafact") public ResponseEntity recibir( @RequestHeader(value = "Ecuafact-Signature", defaultValue = "") String cabecera, @RequestBody byte[] cuerpo) throws Exception { String cuerpoCrudo = new String(cuerpo, StandardCharsets.UTF_8); if (!WebhookSignature.verify(System.getenv("ECUAFACT_WEBHOOK_SECRET"), cabecera, cuerpoCrudo, Instant.now(), 300)) { return ResponseEntity.status(401).build(); } JsonNode evento = JSON.readTree(cuerpoCrudo); String tipo = evento.path("eventType").asText(); String recurso = evento.path("resourceId").asText(); if (procesados.add(tipo + "|" + recurso)) { switch (tipo) { case "document.authorized", "document.rejected", "document.failed" -> System.out.println(tipo + " para la operacion " + recurso); default -> System.out.println("Evento sin accion: " + tipo); } } return ResponseEntity.ok().build(); } } ``` Cada framework da acceso al cuerpo crudo de una forma distinta: - **ASP.NET Core.** Lee `Request.Body` directamente. Si recibes el cuerpo como un parámetro tipado (`[FromBody] MiEvento evento`), el framework ya lo deserializó y no tienes los bytes originales. - **Express.js.** Usa el middleware `raw` de Express.js con `{ type: 'application/json' }`, solo en la ruta del webhook. Si registraste `express.json()` de forma global, se ejecuta antes y consume el cuerpo, así que excluye la ruta del webhook o regístrala antes. - **Flask.** `request.get_data()` devuelve el cuerpo crudo. Llama a `request.get_json()` o a `json.loads` solo después de verificar. - **Spring.** `@RequestBody byte[]` entrega los bytes exactos, y `@RequestBody String` también funciona, porque Spring entrega el texto sin interpretar el JSON y lo decodifica con el `charset=utf-8` de la cabecera. Lo que no funciona es un POJO como `@RequestBody MiEvento evento`, porque Jackson lo deserializa y pierdes el cuerpo original. - **PHP.** Lee `php://input`. No uses `$_POST`, porque con `application/json` viene vacío. ## Probar en local Puedes probar tu endpoint en tu computador antes de publicarlo. Como el destino exige una URL pública con HTTPS en el puerto 443, te recomendamos hacerlo en dos pasos: primero simulas una entrega firmada en tu equipo y después recibes eventos reales a través de un túnel. **1. Simula una entrega firmada** contra tu servidor local, sin pasar por el portal. Usa el mismo secreto que configuraste en tu servidor; para esta prueba puede ser cualquier texto. Ajusta `URL` al puerto de tu ejemplo, que es 3000 en Node.js, Python, PHP y .NET, y 8080 en Spring Boot. La pestaña CLI hace lo mismo con `ecuafact webhooks probar`, que lee el secreto de `ECUAFACT_WEBHOOK_SECRET`. ```bash URL="${URL:-http://localhost:3000/webhooks/ecuafact}" SECRETO="$ECUAFACT_WEBHOOK_SECRET" T=$(date +%s) CUERPO='{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}' FIRMA=$(printf '%s' "$T.$CUERPO" | openssl dgst -sha256 -hmac "$SECRETO" | sed 's/^.*= //') curl -s -i -X POST "$URL" \ -H "Content-Type: application/json; charset=utf-8" \ -H "Ecuafact-Signature: t=$T,v1=$FIRMA" \ --data-binary "$CUERPO" ``` ```python import hashlib import hmac import os import time import requests url = os.environ.get("URL", "http://localhost:3000/webhooks/ecuafact") secreto = os.environ["ECUAFACT_WEBHOOK_SECRET"] cuerpo = ('{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01",' '"claveAcceso":"0710202601012345678900110010010000001231234567811",' '"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",' '"occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}') t = str(int(time.time())) firma = hmac.new(secreto.encode("utf-8"), f"{t}.{cuerpo}".encode("utf-8"), hashlib.sha256).hexdigest() r = requests.post( url, data=cuerpo.encode("utf-8"), headers={"Content-Type": "application/json; charset=utf-8", "Ecuafact-Signature": f"t={t},v1={firma}"}, timeout=30, ) print(r.status_code, r.text) ``` ```bash-cli # Envía un document.authorized firmado con ECUAFACT_WEBHOOK_SECRET. # Resultado esperado: estadoHttp 200 y resultado "correcto". ecuafact webhooks probar --a http://localhost:3000/webhooks/ecuafact # Envía un rechazo fiscal, con codEstado 3001. ecuafact webhooks probar --a http://localhost:3000/webhooks/ecuafact --evento document.rejected # Envía un document.failed con codEstado 4002, firma electrónica no válida. ecuafact webhooks probar --a http://localhost:3000/webhooks/ecuafact --evento document.failed --cod-estado 4002 # Envía una firma incorrecta. Resultado esperado: estadoHttp 401 y resultado "correcto". ecuafact webhooks probar --a http://localhost:3000/webhooks/ecuafact --firma-invalida ``` Con los ejemplos HTTP, el resultado esperado es un 200 la primera vez, y tu servidor imprime "Autorizado ...". Si repites el mismo cuerpo, tu servidor responde 200 sin volver a procesarlo, porque es un duplicado. Si cambias un solo carácter del cuerpo después de firmar o usas otro secreto, responde 401. El CLI usa un `idOperacion` nuevo en cada envío; para probar un duplicado, repite el comando con `--id-operacion` y el mismo valor. **2. Recibe eventos reales con un túnel.** Un túnel publica tu puerto local en una URL pública con HTTPS. Hay varias herramientas gratuitas para hacerlo, por ejemplo estas: ```bash # Con ngrok ngrok http 3000 # Con cloudflared cloudflared tunnel --url http://localhost:3000 ``` 1. Copia la URL `https://...` que muestra la herramienta y agrégale la ruta: `https:///webhooks/ecuafact`. 2. En el portal de **pruebas**, crea un **Nuevo destino** con esa URL y guarda el secreto en la variable `ECUAFACT_WEBHOOK_SECRET` de tu servidor local. Reinicia el servidor para que lo lea. 3. Pulsa **Probar** y revisa que tu servidor reciba `operation.requires_attention` y que **Entregas** muestre HTTP 200. 4. Emite un comprobante de pruebas, como en [Primeros pasos](/v1/guias/primeros-pasos), y espera el `document.authorized` o el `document.rejected`. La URL de muchos túneles gratuitos cambia cada vez que reinicias la herramienta. Cuando cambie, crea un destino nuevo y deshabilita el anterior, porque si no, el destino viejo acumula fallos y termina pausado. ## Errores frecuentes | Síntoma | Causa probable | Qué hacer | |---|---|---| | Tu servidor responde 401 a todas las entregas. | Verificas sobre el JSON re-serializado, usas otro secreto o decodificas el secreto como Base64. | Verifica sobre el cuerpo crudo y usa el secreto tal como lo mostró el portal. Más detalle en [Verificación de firma](/v1/guias/webhooks-firma#errores-frecuentes). | | El portal rechaza la URL al crear el destino. | La URL no es HTTPS, usa un puerto distinto del 443, incluye usuario y clave, o resuelve a una IP privada. | Revisa los [Requisitos de la URL](#requisitos-de-la-url). | | **Entregas** muestra un guion en la columna HTTP y la entrega se reintenta. | Tu servidor no respondió en 15 segundos o no se pudo conectar por DNS, TLS o firewall. La causa exacta está en **Intentos**. | Responde 200 antes de procesar tareas largas y revisa el certificado TLS de tu dominio. | | **Entregas** muestra **Rechazado por tu servidor (HTTP 301)** o 302. | La URL redirige, por ejemplo porque falta o sobra una barra final o porque redirige desde `www`. No se reintenta. | Crea un destino con la URL final exacta, deshabilita el anterior y usa **Reenviar** en las entregas rechazadas. | | **Entregas** muestra **Rechazado por tu servidor** con 401, 403, 404 u otro 4xx. | Tu endpoint rechazó la entrega por una firma no verificada, una ruta inexistente o una autenticación propia. No se reintenta. | Corrige tu endpoint y usa **Reenviar** en cada entrega rechazada. | | El destino aparece **Pausado**. | Hubo 8 fallos consecutivos sin respuesta o con 408, 429 o 5xx. | Corrige la causa, pulsa **Reanudar** y revisa en el seguimiento las operaciones que quedaron sin resultado. | | Procesas dos veces el mismo comprobante. | Tu servidor no descarta los duplicados. | Aplica la clave única `eventType` + `resourceId`. | ## Siguientes pasos - [Verificación de firma](/v1/guias/webhooks-firma): sigue el algoritmo paso a paso, prueba con el vector publicado y rota el secreto sin perder entregas. - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta el estado actual de una operación cuando necesitas confirmarlo. - [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida): entiende cómo se relacionan la emisión, el resultado del SRI y los eventos. - [Errores](/v1/guias/errores#catalogo-de-codestado): consulta qué significa cada `codEstado` que llega en el cuerpo de un evento. --- # Verificación de firma Comprueba que cada webhook te lo enviamos nosotros y que nadie lo alteró, con un HMAC-SHA256 del cuerpo crudo calculado con tu secreto. Tu endpoint de webhooks es una URL pública, así que cualquiera puede enviarle una petición. Antes de procesar un evento, tu servidor debe comprobar su firma: es la única forma de saber que te lo enviamos nosotros y que el cuerpo llegó tal como salió. Esta página explica cómo se forma la cabecera de firma, el algoritmo para verificarla paso a paso y ejemplos listos en cada lenguaje, con un vector de prueba para confirmar que tu código calcula bien. También explica las cabeceras del estándar abierto Standard Webhooks, que traen la misma entrega firmada para que puedas verificarla con una librería, cuánta diferencia de tiempo aceptar, cómo rotar el secreto sin perder entregas y qué revisar cuando la verificación falla. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. El algoritmo es el mismo en pruebas y > en producción, y cada destino tiene su propio secreto. ## Conceptos Calculamos un HMAC-SHA256 sobre el cuerpo que te enviamos y lo ponemos en la cabecera `Ecuafact-Signature`. Un HMAC es un código que solo puede generar quien conoce el secreto, así que tu servidor repite el cálculo con el mismo secreto y, si los dos valores coinciden, sabe que el evento es auténtico y que nadie modificó el cuerpo en el camino. La firma incluye además una marca de tiempo. Gracias a ella, nadie puede capturar un evento válido y reenviártelo días después, lo que se conoce como un ataque de repetición. Cada entrega trae la firma en dos formatos, calculados con el mismo secreto: `Ecuafact-Signature`, nuestra cabecera de siempre, y las cabeceras de [Standard Webhooks](#standard-webhooks). Basta con que verifiques una. ## Prerequisitos - [ ] El secreto del destino, guardado en `ECUAFACT_WEBHOOK_SECRET`. El portal lo muestra una sola vez, al crear el destino o al rotarlo en **Integración > Eventos**, como se explica en [Webhooks](/v1/guias/webhooks#configurar-el-destino-en-el-portal). - [ ] Acceso al **cuerpo crudo** de la petición en tu framework, es decir, a los bytes tal como llegaron, antes de deserializarlos. - [ ] El reloj de tu servidor sincronizado por NTP, para validar la marca de tiempo. ## La cabecera Ecuafact-Signature Cada entrega trae una cabecera como esta: ``` Ecuafact-Signature: t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20 ``` | Parte | Formato | Descripción | |---|---|---| | `t` | Entero, segundos Unix (UTC) | Momento en que se firmó **esta** entrega. Cambia en cada reintento. | | `v1` | 64 caracteres hexadecimales en minúsculas | HMAC-SHA256 de la cadena firmada, con tu secreto como clave. | Las partes van separadas por coma y cada una tiene la forma `nombre=valor`. Lee cada parte por su nombre y no por su posición, e ignora cualquier parte distinta de `t` y `v1`. El secreto es un texto de 44 caracteres, por ejemplo `c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=`. Aunque parece Base64, **úsalo tal cual**, porque la clave del HMAC son los bytes UTF-8 de ese texto y no el resultado de decodificarlo. ## Cadena firmada El valor `v1` es el HMAC-SHA256 de esta cadena: ``` + "." + ``` - `` es el valor de `t` de la cabecera, como texto; por ejemplo, 1791385446. - `` es el cuerpo de la petición **exactamente** como llegó, sin reindentar, reordenar claves ni quitar espacios. El cuerpo llega en UTF-8. ## Algoritmo paso a paso Tu servidor verifica cada entrega con estos pasos, en este orden: 1. Lee la cabecera `Ecuafact-Signature`. Si falta, rechaza la entrega con un 401. 2. Separa la cabecera por comas, quita los espacios de cada parte y obtén `t` y `v1`. Si falta alguno o `t` no es un entero, rechaza la entrega. 3. Compara `t` con tu reloj. Si la diferencia es mayor que tu tolerancia, que te recomendamos fijar en 300 segundos, rechaza la entrega. 4. Construye la cadena `t + "." + cuerpo_crudo`. 5. Calcula HMAC-SHA256 de esa cadena (bytes UTF-8) con el secreto (bytes UTF-8) como clave. 6. Convierte el resultado a hexadecimal en **minúsculas**. 7. Compara tu resultado con `v1`, pasado a minúsculas, usando una comparación de **tiempo constante**. Si no coinciden, rechaza la entrega. 8. Solo ahora interpreta el JSON y procesa el evento. > [!WARNING] > Calcula el HMAC sobre el cuerpo crudo. Si tu framework deserializa el JSON y > lo vuelves a serializar, la firma no coincide aunque el contenido sea el mismo. > Y nunca proceses un evento cuya firma no verificaste, porque cualquiera puede > llamar a tu URL. ## Verificación Cada ejemplo define la función de verificación y la prueba con el [vector de prueba](#vector-de-prueba). Si tu código está bien, imprime `true` (o `True` en Python). La función recibe el instante actual como parámetro para que puedas probarla con un vector de fecha fija; en tu endpoint, pásale la hora actual. Las pestañas SDK usan el verificador incluido en cada SDK oficial, y la pestaña CLI verifica la misma firma con `ecuafact webhooks verificar`, que lee el secreto de `ECUAFACT_WEBHOOK_SECRET`. ```bash # Herramienta de diagnostico: no compara en tiempo constante. No la uses en produccion. SECRETO='c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=' CABECERA='t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20' CUERPO='{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}' T=$(printf '%s' "$CABECERA" | sed -n 's/.*t=\([0-9]*\).*/\1/p') V1=$(printf '%s' "$CABECERA" | sed -n 's/.*v1=\([0-9a-fA-F]*\).*/\1/p' | tr 'A-F' 'a-f') ESPERADO=$(printf '%s' "$T.$CUERPO" | openssl dgst -sha256 -hmac "$SECRETO" | sed 's/^.*= //') [ "$ESPERADO" = "$V1" ] && echo "true" || echo "false" ``` ```csharp using System.Security.Cryptography; using System.Text; const string Secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="; const string Cabecera = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20"; const string Cuerpo = """{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}"""; // En tu endpoint: ahora = DateTimeOffset.UtcNow.ToUnixTimeSeconds() Console.WriteLine(Verificar(Secreto, Cabecera, Cuerpo, ahora: 1791385446, toleranciaSegundos: 300)); static bool Verificar(string secreto, string cabecera, string cuerpoCrudo, long ahora, long toleranciaSegundos) { string? t = null; string? v1 = null; foreach (string parte in cabecera.Split(',')) { string item = parte.Trim(); if (item.StartsWith("t=", StringComparison.Ordinal)) { t = item.Substring(2); } else if (item.StartsWith("v1=", StringComparison.Ordinal)) { v1 = item.Substring(3); } } if (t == null || v1 == null || !long.TryParse(t, out long unix)) { return false; } if (Math.Abs(ahora - unix) > toleranciaSegundos) { return false; } using HMACSHA256 hmac = new(Encoding.UTF8.GetBytes(secreto)); byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(t + "." + cuerpoCrudo)); string esperado = Convert.ToHexString(hash).ToLowerInvariant(); // ToHexString devuelve MAYUSCULAS return CryptographicOperations.FixedTimeEquals( Encoding.ASCII.GetBytes(esperado), Encoding.ASCII.GetBytes(v1.ToLowerInvariant())); } ``` ```python import hashlib import hmac import time SECRETO = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=" CABECERA = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20" CUERPO = ('{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01",' '"claveAcceso":"0710202601012345678900110010010000001231234567811",' '"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",' '"occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}') def verificar(secreto, cabecera, cuerpo_crudo, ahora=None, tolerancia=300): partes = dict(p.strip().split("=", 1) for p in cabecera.split(",") if "=" in p) t, v1 = partes.get("t"), partes.get("v1") if not t or not v1 or not t.isdigit(): return False ahora = int(time.time()) if ahora is None else ahora if abs(ahora - int(t)) > tolerancia: return False firmado = f"{t}.{cuerpo_crudo}".encode("utf-8") esperado = hmac.new(secreto.encode("utf-8"), firmado, hashlib.sha256).hexdigest() return hmac.compare_digest(esperado, v1.lower()) # En tu endpoint omite "ahora" para usar la hora actual. print(verificar(SECRETO, CABECERA, CUERPO, ahora=1791385446)) ``` ```javascript // Node.js 18 o superior. Guarda como firma.mjs y ejecuta: node firma.mjs import { createHmac, timingSafeEqual } from 'node:crypto'; const SECRETO = 'c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ='; const CABECERA = 't=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20'; const CUERPO = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}'; function verificar(secreto, cabecera, cuerpoCrudo, ahora = Math.floor(Date.now() / 1000), tolerancia = 300) { let t = null; let v1 = null; for (const parte of cabecera.split(',')) { const item = parte.trim(); if (item.startsWith('t=')) t = item.slice(2); else if (item.startsWith('v1=')) v1 = item.slice(3).toLowerCase(); } if (!t || !v1 || !/^\d+$/.test(t)) return false; if (Math.abs(ahora - Number(t)) > tolerancia) return false; const esperado = createHmac('sha256', secreto).update(`${t}.${cuerpoCrudo}`, 'utf8').digest('hex'); const a = Buffer.from(esperado, 'utf8'); const b = Buffer.from(v1, 'utf8'); return a.length === b.length && timingSafeEqual(a, b); } // En tu endpoint omite "ahora" para usar la hora actual. console.log(verificar(SECRETO, CABECERA, CUERPO, 1791385446)); ``` ```php $tolerancia) { return false; } $esperado = hash_hmac('sha256', $t . '.' . $cuerpoCrudo, $secreto); return hash_equals($esperado, strtolower($v1)); } // En tu endpoint omite $ahora para usar la hora actual. var_dump(verificar($secreto, $cabecera, $cuerpo, 1791385446)); ``` ```java import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.HashMap; import java.util.Map; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class Firma { public static void main(String[] args) throws Exception { String secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="; String cabecera = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20"; String cuerpo = """ {"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}"""; // En tu endpoint: ahora = java.time.Instant.now().getEpochSecond() System.out.println(verificar(secreto, cabecera, cuerpo, 1791385446L, 300)); } static boolean verificar(String secreto, String cabecera, String cuerpoCrudo, long ahora, long tolerancia) throws Exception { Map partes = new HashMap<>(); for (String p : cabecera.split(",")) { String[] kv = p.trim().split("=", 2); if (kv.length == 2) { partes.put(kv[0], kv[1]); } } String t = partes.get("t"); String v1 = partes.get("v1"); if (t == null || v1 == null || !t.matches("\\d+")) { return false; } if (Math.abs(ahora - Long.parseLong(t)) > tolerancia) { return false; } Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(secreto.getBytes(StandardCharsets.UTF_8), "HmacSHA256")); byte[] hash = mac.doFinal((t + "." + cuerpoCrudo).getBytes(StandardCharsets.UTF_8)); StringBuilder hex = new StringBuilder(); for (byte b : hash) { hex.append(String.format("%02x", b)); } return MessageDigest.isEqual( hex.toString().getBytes(StandardCharsets.US_ASCII), v1.toLowerCase().getBytes(StandardCharsets.US_ASCII)); } } ``` ```csharp-sdk using Ecuafact.Sdk.Webhooks; const string Secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="; const string Cabecera = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20"; const string Cuerpo = """{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}"""; // En tu endpoint usa DateTimeOffset.UtcNow en lugar del instante fijo del vector. bool valido = WebhookSignature.Verify(Secreto, Cabecera, Cuerpo, DateTimeOffset.FromUnixTimeSeconds(1791385446), TimeSpan.FromMinutes(5)); Console.WriteLine(valido); ``` ```python-sdk from ecuafact import verify SECRETO = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=" CABECERA = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20" CUERPO = ('{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01",' '"claveAcceso":"0710202601012345678900110010010000001231234567811",' '"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",' '"occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}') # En tu endpoint omite "now" para usar la hora actual. print(verify(SECRETO, CABECERA, CUERPO, now=1791385446, tolerance_seconds=300)) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como firma.mjs y ejecuta: node firma.mjs import { verify } from "@ecuafact/sdk"; const SECRETO = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="; const CABECERA = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20"; const CUERPO = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}'; // En tu endpoint usa new Date() en lugar del instante fijo del vector. console.log(verify(SECRETO, CABECERA, CUERPO, new Date(1791385446 * 1000), 300)); ``` ```php-sdk evento.json export ECUAFACT_WEBHOOK_SECRET='c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=' # --ahora fija el instante del vector; con un webhook real, omítelo. # Resultado esperado: valida si, motivo "Firma valida." ecuafact webhooks verificar --firma "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20" --cuerpo @evento.json --ahora 1791385446 ``` Esta tabla resume cómo se llama el verificador de cada SDK y qué parámetros recibe: | SDK | Función | Instante actual | Tolerancia | |---|---|---|---| | .NET (`Ecuafact.Sdk`) | `Ecuafact.Sdk.Webhooks.WebhookSignature.Verify(secret, header, body, now, tolerance)` | `DateTimeOffset now` | `TimeSpan tolerance` | | Python (`ecuafact`) | `ecuafact.verify(secret, header, body, now=None, tolerance_seconds=300)` | segundos Unix; `None` = ahora | segundos | | Node.js (`@ecuafact/sdk`) | `verify(secret, header, body, now = new Date(), toleranceSeconds = 300)` | `Date` | segundos | | PHP (`ecuafact/sdk`) | `Ecuafact\Sdk\WebhookSignature::verify($secret, $header, $body, ?int $now = null, int $toleranceSeconds = 300)` | segundos Unix; `null` = ahora | segundos | | Java (`com.ecuafact:sdk`) | `com.ecuafact.sdk.WebhookSignature.verify(secret, header, body, Instant now, long toleranceSeconds)` | `Instant` | segundos | Todos devuelven `false`, sin lanzar una excepción, si la cabecera falta o está mal formada, si la marca de tiempo está fuera de la tolerancia o si la firma no coincide. Todos aceptan `v1` en mayúsculas o minúsculas y comparan en tiempo constante. En `secret` también aceptan una lista de secretos, y la entrega es válida si coincide con cualquiera de ellos, lo que te sirve durante la [rotación del secreto](#rotacion-de-secreto). Los SDK verifican también la firma de [Standard Webhooks](#standard-webhooks), y traen un verificador que recibe las cabeceras de la petición y acepta cualquiera de las dos firmas: comprueba `Ecuafact-Signature` y, si falta o no coincide, las cabeceras de Standard Webhooks. Es la forma recomendada de verificar con un SDK, porque funciona igual llegue la firma que llegue. Las mismas reglas valen para los dos: devuelven `false` sin lanzar una excepción, aceptan el secreto con o sin el prefijo `whsec_` y aceptan una lista de secretos para la rotación. | SDK | Solo Standard Webhooks | Cualquiera de las dos firmas | Evento tipado con cualquiera de las dos | |---|---|---|---| | .NET | `StandardWebhookSignature.Verify(secreto, id, timestamp, firma, cuerpo)` | `WebhookSignature.VerificarEntrega(secretos, nombre => Request.Headers[nombre], cuerpo)` | `WebhookEvent.ConstruirDesdeEntrega(secretos, nombre => Request.Headers[nombre], cuerpo)` | | Node.js | `verificarStandardWebhooks(secreto, { webhookId, webhookTimestamp, webhookSignature }, cuerpo)` | `verificarWebhook(secreto, req.headers, cuerpo)` | `construirEventoDesdeCabeceras(secreto, req.headers, cuerpo)` | | Python | `ecuafact.verificar_estandar(secreto, webhook_id, webhook_timestamp, webhook_signature, cuerpo)` | `ecuafact.verificar_webhook(secreto, request.headers, cuerpo)` | `ecuafact.construir_evento_webhook(secreto, request.headers, cuerpo)` | | PHP | `WebhookSignature::verificarStandardWebhooks($secreto, $id, $timestamp, $firma, $cuerpo)` | `WebhookSignature::verificarCabeceras($secreto, getallheaders(), $cuerpo)` | `WebhookEvent::construirDesdeCabeceras($secreto, getallheaders(), $cuerpo)` | | Java | `WebhookSignature.verificarEstandar(secreto, id, timestamp, firma, cuerpo)` | `WebhookSignature.verificarCualquiera(secreto, cabeceras, cuerpo)` (o `request::getHeader`) | `WebhookEvent.construirConCabeceras(secretos, cabeceras, cuerpo)` | En todos, `cuerpo` es el **cuerpo crudo** de la petición, tal como llegó, y la tolerancia por defecto es de 300 segundos. ## Vector de prueba Usa estos vectores para probar tu función de HMAC. En los dos, el cuerpo es una sola línea, sin salto de línea final. Como `t` es una fecha fija, tu verificación completa fallará por tolerancia si usas la hora actual. Por eso, prueba el cálculo del HMAC por separado o pasa el instante del vector, como hacen los ejemplos. **Vector 1: evento completo**, con un secreto del mismo formato que los reales. | Dato | Valor | |---|---| | Secreto | `c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=` | | `t` | `1791385446` (2026-10-07 15:04:06 UTC) | | Cuerpo crudo | `{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}` | | Cadena firmada | `1791385446.` seguido del cuerpo crudo | | `v1` esperado | `3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20` | | Cabecera | `Ecuafact-Signature: t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20` | **Vector 2: cuerpo mínimo.** | Dato | Valor | |---|---| | Secreto | `whsec_pruebas` | | `t` | `1757341445` | | Cuerpo crudo | `{"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"}` | | `v1` esperado | `e3b03c6de58fd0565b83be8c2c83b0fb68dafe66edd06c568e57c5d48e992228` | ```bash printf '%s' '1757341445.{"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"}' \ | openssl dgst -sha256 -hmac "whsec_pruebas" # e3b03c6de58fd0565b83be8c2c83b0fb68dafe66edd06c568e57c5d48e992228 ``` Si con el vector 1 obtienes uno de estos valores en lugar del esperado, la tabla te dice qué falla: | Obtienes | Causa | Corrección | |---|---|---| | `219caea9414d73dfe03866573a5e60fe02135c95c119e74b79ccbc1255c324f1` | Decodificaste el secreto como Base64. | Usa los bytes UTF-8 del texto del secreto, sin decodificar. | | `68a67ed5142f10c742ad26a4b7c763e74443d564fba6032c1f66aae912692a65` | Firmaste el JSON re-serializado, con `", "` y `": "` como separadores, que es el formato por defecto de `json.dumps` de Python. | Firma el cuerpo crudo. | | `3E236507...` (mayúsculas) | Tu biblioteca devuelve el hexadecimal en mayúsculas, como hace `Convert.ToHexString` en .NET. | Pasa el valor a minúsculas antes de comparar. | ## Standard Webhooks Cada entrega trae también las tres cabeceras de [Standard Webhooks](https://www.standardwebhooks.com), un estándar abierto para firmar webhooks que ya usan otras plataformas y que tiene librerías oficiales en varios lenguajes. Puedes verificar cualquiera de las dos firmas: las dos cubren el mismo cuerpo, llegan en todas las entregas y se calculan con el mismo secreto. Si empiezas una integración nueva, te recomendamos el estándar, porque puedes verificarlo con una librería en lugar de escribir el código. | Cabecera | Ejemplo | Descripción | |---|---|---| | `webhook-id` | `9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b` | Identificador del evento. Es el mismo en todos los reintentos y en cada **Reenviar**, así que también te sirve para descartar duplicados. | | `webhook-timestamp` | `1791385446` | Segundos Unix (UTC) en que se firmó **esta** entrega. Es el mismo valor que `t` en `Ecuafact-Signature` y cambia en cada reintento. | | `webhook-signature` | `v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=` | Lista de firmas separadas por espacios. Cada firma es `v1,` seguido del HMAC-SHA256 en Base64. Enviamos una sola, pero lee la lista completa y acepta la entrega si coincide cualquiera. | La firma es el HMAC-SHA256 de esta cadena: ``` + "." + + "." + ``` > [!WARNING] > La clave del HMAC es distinta en cada esquema. En `Ecuafact-Signature` la clave > son los bytes UTF-8 del texto del secreto. En Standard Webhooks la clave son > los 32 bytes que resultan de **decodificar el secreto como Base64**. Las > librerías del estándar aceptan el secreto tal como lo muestra el portal o con > el prefijo `whsec_` delante (`whsec_c2VjcmV0by1k...`), y lo decodifican por ti. Para verificar una entrega con el estándar, tu servidor sigue estos pasos: 1. Lee las tres cabeceras. Si falta alguna, rechaza la entrega con un 401. 2. Compara `webhook-timestamp` con tu reloj y rechaza la entrega si la diferencia supera tu tolerancia, que te recomendamos fijar en 300 segundos. 3. Quita el prefijo `whsec_` del secreto, si lo tiene, y decodifícalo como Base64 para obtener la clave. 4. Calcula el HMAC-SHA256 de `webhook-id + "." + webhook-timestamp + "." + cuerpo_crudo` en bytes UTF-8 y codifícalo en Base64. 5. Separa `webhook-signature` por espacios y, de cada firma que empiece con `v1,`, compara lo que sigue a la coma con tu resultado, usando una comparación de tiempo constante. Si ninguna coincide, rechaza la entrega. 6. Solo ahora interpreta el JSON y procesa el evento. Cada ejemplo verifica el [vector 3](#vector-3-standard-webhooks) e imprime `true` (o `True` en Python). Los SDK verifican esta firma por sí mismos. En el modo SDK, las pestañas de Node.js y Python muestran además las librerías oficiales del estándar, que comprueban la marca de tiempo con la hora actual y por eso no aceptan el vector de fecha fija; con un webhook real devuelven el evento ya interpretado y lanzan `WebhookVerificationError` si la firma no coincide. La pestaña CLI verifica las mismas cabeceras con `ecuafact webhooks verificar`. ```bash # Herramienta de diagnostico: no compara en tiempo constante. No la uses en produccion. SECRETO='c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=' ID='9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b' MARCA='1791385446' FIRMAS='v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=' CUERPO='{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}' CLAVE_HEX=$(printf '%s' "${SECRETO#whsec_}" | base64 -d | od -An -tx1 | tr -d ' \n') ESPERADO=$(printf '%s' "$ID.$MARCA.$CUERPO" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$CLAVE_HEX" -binary | base64) case " $FIRMAS " in *" v1,$ESPERADO "*) echo "true" ;; *) echo "false" ;; esac ``` ```csharp using System.Security.Cryptography; using System.Text; const string Secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="; const string Id = "9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b"; const string Marca = "1791385446"; const string Firmas = "v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8="; const string Cuerpo = """{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}"""; // En tu endpoint: ahora = DateTimeOffset.UtcNow.ToUnixTimeSeconds() Console.WriteLine(VerificarEstandar(Secreto, Id, Marca, Firmas, Cuerpo, ahora: 1791385446, toleranciaSegundos: 300)); static bool VerificarEstandar(string secreto, string id, string marca, string firmas, string cuerpoCrudo, long ahora, long toleranciaSegundos) { if (!long.TryParse(marca, out long t) || Math.Abs(ahora - t) > toleranciaSegundos) { return false; } byte[] clave = Convert.FromBase64String(secreto.StartsWith("whsec_", StringComparison.Ordinal) ? secreto[6..] : secreto); byte[] esperado = HMACSHA256.HashData(clave, Encoding.UTF8.GetBytes(id + "." + marca + "." + cuerpoCrudo)); foreach (string firma in firmas.Split(' ', StringSplitOptions.RemoveEmptyEntries)) { byte[] recibida = new byte[firma.Length]; if (firma.StartsWith("v1,", StringComparison.Ordinal) && Convert.TryFromBase64String(firma[3..], recibida, out int largo) && CryptographicOperations.FixedTimeEquals(recibida.AsSpan(0, largo), esperado)) { return true; } } return false; } ``` ```python import base64 import hashlib import hmac import time SECRETO = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=" ID = "9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b" MARCA = "1791385446" FIRMAS = "v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=" CUERPO = ('{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01",' '"claveAcceso":"0710202601012345678900110010010000001231234567811",' '"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",' '"occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}') def verificar_estandar(secreto, id_evento, marca, firmas, cuerpo_crudo, ahora=None, tolerancia=300): if not marca.isdigit(): return False ahora = int(time.time()) if ahora is None else ahora if abs(ahora - int(marca)) > tolerancia: return False clave = base64.b64decode(secreto.removeprefix("whsec_")) firmado = f"{id_evento}.{marca}.{cuerpo_crudo}".encode("utf-8") esperado = base64.b64encode(hmac.new(clave, firmado, hashlib.sha256).digest()).decode() return any(f.startswith("v1,") and hmac.compare_digest(f[3:], esperado) for f in firmas.split(" ")) # En tu endpoint omite "ahora" para usar la hora actual. print(verificar_estandar(SECRETO, ID, MARCA, FIRMAS, CUERPO, ahora=1791385446)) ``` ```javascript // Node.js 18 o superior. Guarda como firma-estandar.mjs y ejecuta: node firma-estandar.mjs import { createHmac, timingSafeEqual } from 'node:crypto'; const SECRETO = 'c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ='; const ID = '9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b'; const MARCA = '1791385446'; const FIRMAS = 'v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8='; const CUERPO = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}'; function verificarEstandar(secreto, id, marca, firmas, cuerpoCrudo, ahora = Math.floor(Date.now() / 1000), tolerancia = 300) { if (!/^\d+$/.test(marca) || Math.abs(ahora - Number(marca)) > tolerancia) return false; const clave = Buffer.from(secreto.replace(/^whsec_/, ''), 'base64'); const esperado = createHmac('sha256', clave).update(`${id}.${marca}.${cuerpoCrudo}`, 'utf8').digest(); return firmas.split(' ').some((firma) => { if (!firma.startsWith('v1,')) return false; const recibida = Buffer.from(firma.slice(3), 'base64'); return recibida.length === esperado.length && timingSafeEqual(recibida, esperado); }); } // En tu endpoint omite "ahora" para usar la hora actual. console.log(verificarEstandar(SECRETO, ID, MARCA, FIRMAS, CUERPO, 1791385446)); ``` ```php $tolerancia) { return false; } $clave = base64_decode(preg_replace('/^whsec_/', '', $secreto), true); if ($clave === false) { return false; } $esperado = base64_encode(hash_hmac('sha256', $id . '.' . $marca . '.' . $cuerpoCrudo, $clave, true)); foreach (explode(' ', $firmas) as $firma) { if (str_starts_with($firma, 'v1,') && hash_equals($esperado, substr($firma, 3))) { return true; } } return false; } // En tu endpoint omite $ahora para usar la hora actual. var_dump(verificarEstandar($secreto, $id, $marca, $firmas, $cuerpo, 1791385446)); ``` ```java import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.Base64; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class FirmaEstandar { public static void main(String[] args) throws Exception { String secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="; String id = "9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b"; String marca = "1791385446"; String firmas = "v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8="; String cuerpo = """ {"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}"""; // En tu endpoint: ahora = java.time.Instant.now().getEpochSecond() System.out.println(verificarEstandar(secreto, id, marca, firmas, cuerpo, 1791385446L, 300)); } static boolean verificarEstandar(String secreto, String id, String marca, String firmas, String cuerpoCrudo, long ahora, long tolerancia) throws Exception { if (!marca.matches("\\d+") || Math.abs(ahora - Long.parseLong(marca)) > tolerancia) { return false; } byte[] clave = Base64.getDecoder().decode(secreto.startsWith("whsec_") ? secreto.substring(6) : secreto); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(clave, "HmacSHA256")); byte[] esperado = mac.doFinal((id + "." + marca + "." + cuerpoCrudo).getBytes(StandardCharsets.UTF_8)); for (String firma : firmas.split(" ")) { if (!firma.startsWith("v1,")) { continue; } try { if (MessageDigest.isEqual(Base64.getDecoder().decode(firma.substring(3)), esperado)) { return true; } } catch (IllegalArgumentException e) { // Firma que no es Base64: se ignora y se prueba la siguiente. } } return false; } } ``` ```javascript-sdk // Librería oficial del estándar: npm install standardwebhooks express // Guarda como servidor.mjs y ejecuta: node servidor.mjs import express from 'express'; import { Webhook, WebhookVerificationError } from 'standardwebhooks'; const app = express(); const verificador = new Webhook(process.env.ECUAFACT_WEBHOOK_SECRET); // express.raw entrega el cuerpo crudo, sin interpretar el JSON. app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => { let evento; try { // Comprueba la firma y la marca de tiempo, y devuelve el JSON interpretado. evento = verificador.verify(req.body.toString('utf8'), req.headers); } catch (error) { if (error instanceof WebhookVerificationError) return res.sendStatus(401); throw error; } // Procesa evento.eventType y responde 2xx. res.sendStatus(200); }); app.listen(3000); ``` ```python-sdk # Librería oficial del estándar: pip install standardwebhooks flask # Guarda como servidor.py y ejecuta: flask --app servidor run --port 3000 # request.get_data() devuelve el cuerpo crudo, sin interpretar el JSON. import os from flask import Flask, request from standardwebhooks.webhooks import Webhook, WebhookVerificationError app = Flask(__name__) verificador = Webhook(os.environ["ECUAFACT_WEBHOOK_SECRET"]) @app.post("/webhooks") def webhooks(): try: # Comprueba la firma y la marca de tiempo, y devuelve el JSON interpretado. evento = verificador.verify(request.get_data(as_text=True), dict(request.headers)) except WebhookVerificationError: return "", 401 # Procesa evento["eventType"] y responde 2xx. return "", 200 ``` ```bash-cli # Guarda el cuerpo del vector 3 tal cual, sin salto de línea final. printf '%s' '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}' > evento.json export ECUAFACT_WEBHOOK_SECRET='c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=' # --ahora fija el instante del vector; con un webhook real, omítelo. # Resultado esperado: valida si, esquema standard-webhooks, motivo "Firma valida." ecuafact webhooks verificar --webhook-id 9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b --webhook-timestamp 1791385446 --webhook-signature "v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=" --cuerpo @evento.json --ahora 1791385446 ``` El estándar publica librerías oficiales para más lenguajes, por ejemplo Go, Ruby, Rust, Java y Kotlin, que aceptan el secreto de la misma forma. Las encuentras en [standardwebhooks.com](https://www.standardwebhooks.com). ### Vector 3: Standard Webhooks Usa el mismo secreto y el mismo cuerpo del vector 1. | Dato | Valor | |---|---| | Secreto | `c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=`, o `whsec_c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=` en una librería del estándar | | `webhook-id` | `9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b` | | `webhook-timestamp` | `1791385446` (2026-10-07 15:04:06 UTC) | | Cadena firmada | `9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b.1791385446.` seguido del cuerpo crudo | | `webhook-signature` esperada | `v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=` | Si obtienes `v1,EtTOf62C...` en lugar del valor esperado, usaste el texto del secreto como clave sin decodificarlo, que es lo que pide `Ecuafact-Signature` pero no el estándar. ## Tolerancia de tiempo La tolerancia es la diferencia máxima que aceptas entre la marca de tiempo de la firma y el reloj de tu servidor. Estas son las reglas para elegirla y aplicarla: - Rechaza la entrega si `|ahora - t|` supera tu tolerancia. Te recomendamos **300 segundos**, es decir, 5 minutos, que es el valor por defecto de los SDK. - Cada reintento se firma de nuevo con un `t` actual, así que la tolerancia no rechaza reintentos legítimos aunque el evento original sea de horas antes. Para saber cuándo ocurrió el hecho, usa el `occurredAtUtc` del cuerpo y no `t`. - Mantén el reloj de tu servidor sincronizado por NTP. Un reloj desfasado más que la tolerancia rechaza todas las entregas, y después de 8 fallos consecutivos el destino se pausa. - No uses una tolerancia menor a 60 segundos, porque una entrega puede tardar más que eso en llegar a tu servidor. ## Rotación de secreto Rota el secreto si se expuso, por ejemplo porque quedó en un log o en un repositorio, o como práctica periódica. Para hacerlo, pulsa **Rotar secreto** en el destino, en **Integración > Eventos**. También puedes rotarlo por API con `POST /v1/webhooks/destinos/{id}/rotar-secreto`, que devuelve el secreto nuevo en `secretoUnaVez`, como se explica en [Webhooks](/v1/guias/webhooks#administrar-destinos-por-api). Al rotar, recibes el secreto nuevo una sola vez y **todas las entregas siguientes se firman solo con el secreto nuevo**, incluidos los reintentos de eventos anteriores. Como no enviamos una segunda firma con el secreto anterior, sigue estos pasos para no rechazar entregas durante el cambio: 1. Prepara tu servidor para aceptar **una lista de secretos**, de modo que la entrega sea válida si la firma coincide con cualquiera de ellos. Los ejemplos de abajo muestran cómo. 2. Pulsa **Rotar secreto** y copia el secreto nuevo. 3. Agrega el secreto nuevo a la lista, sin quitar el anterior, y publica el cambio cuanto antes. 4. Las entregas que lleguen entre la rotación y tu publicación fallan la verificación, y las seguimos reintentando con esperas crecientes. Revisa en **Entregas** que vuelvan a mostrar HTTP 200. 5. Cuando las entregas se firmen correctamente con el secreto nuevo, quita el anterior de la lista. ```csharp // Acepta la entrega si la firma coincide con alguno de los secretos vigentes. string[] secretos = { Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET")!, Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET_ANTERIOR") ?? "" }; long ahora = DateTimeOffset.UtcNow.ToUnixTimeSeconds(); bool valido = secretos.Any(s => s.Length > 0 && Verificar(s, cabecera, cuerpoCrudo, ahora, 300)); ``` ```python # Acepta la entrega si la firma coincide con alguno de los secretos vigentes. secretos = [s for s in (os.environ.get("ECUAFACT_WEBHOOK_SECRET"), os.environ.get("ECUAFACT_WEBHOOK_SECRET_ANTERIOR")) if s] valido = any(verificar(s, cabecera, cuerpo_crudo) for s in secretos) ``` ```javascript // Acepta la entrega si la firma coincide con alguno de los secretos vigentes. const secretos = [process.env.ECUAFACT_WEBHOOK_SECRET, process.env.ECUAFACT_WEBHOOK_SECRET_ANTERIOR].filter(Boolean); const valido = secretos.some((s) => verificar(s, cabecera, cuerpoCrudo)); ``` ```php [!WARNING] > Si sospechas que el secreto se filtró, rótalo de inmediato y retira el anterior > en cuanto publiques el nuevo, porque mientras lo aceptes, quien lo tenga puede > enviarte eventos falsos. ## Errores frecuentes Si la verificación falla, busca el síntoma en esta tabla. | Error | Síntoma | Corrección | |---|---|---| | Cuerpo re-serializado | Todas las firmas fallan aunque el secreto sea correcto. | Lee el cuerpo crudo antes de cualquier deserialización (`Request.Body`, el middleware `raw` de Express.js, `request.get_data()`, `php://input`, `@RequestBody byte[]`). | | Cuerpo modificado en el camino | Las firmas fallan solo detrás de cierto proxy, WAF o middleware. | Revisa que nada entre nuestro envío y tu código reescriba el cuerpo, por ejemplo al minificarlo, reindentarlo, cambiar su codificación o agregarle un salto de línea final. | | Codificación incorrecta | La verificación falla con algunos cuerpos y no con otros. | Decodifica el cuerpo como UTF-8, o firma directamente los bytes, y convierte la cadena firmada a bytes UTF-8. No uses Latin-1 ni la codificación por defecto del sistema. | | Secreto decodificado como Base64 | La firma de `Ecuafact-Signature` es distinta en todos los casos; con el vector 1 obtienes `219caea9...`. | Usa el texto del secreto como clave, en UTF-8. | | Secreto sin decodificar en Standard Webhooks | La firma de `webhook-signature` es distinta en todos los casos; con el vector 3 obtienes `v1,EtTOf62C...`. | Quita el prefijo `whsec_` si lo tiene y decodifica el secreto como Base64, o usa una librería del estándar. | | Cadena del estándar mal armada | `webhook-signature` no coincide aunque la clave sea la correcta. | Firma `webhook-id + "." + webhook-timestamp + "." + cuerpo_crudo`, con los valores de las cabeceras. | | Secreto con espacios o salto de línea | La firma es distinta en todos los casos. | Al copiar el secreto del portal o leerlo de un archivo, quita los espacios y saltos de línea del inicio y del final. | | Hexadecimal en mayúsculas | La comparación falla aunque el valor sea correcto. | Convierte tu resultado y `v1` a minúsculas antes de comparar. | | Comparación no constante | La verificación funciona, pero `==` o `equals` revela por tiempo cuántos caracteres coinciden. | Usa `CryptographicOperations.FixedTimeEquals`, `hmac.compare_digest`, `crypto.timingSafeEqual`, `hash_equals` o `MessageDigest.isEqual`. | | Cadena firmada mal armada | La firma es distinta porque falta el punto, usas tu propio reloj en lugar de `t` o pones el cuerpo antes de `t`. | Firma exactamente `t + "." + cuerpo_crudo`, con el `t` de la cabecera. | | Lectura posicional de la cabecera | La verificación falla si cambia el orden o se agrega una parte nueva. | Lee `t` y `v1` por su nombre. | | Reloj desfasado | Todas las entregas fallan por tolerancia. | Sincroniza el reloj por NTP y usa una tolerancia de 300 segundos. | | Secreto de otro destino o ambiente | Fallan todas las entregas de un destino. | Cada destino, y cada ambiente, tiene su propio secreto. Usa el del destino que recibe. | ## Siguientes pasos - [Webhooks](/v1/guias/webhooks): configura el destino y conoce los eventos, los reintentos y cómo descartar duplicados. - [SDK .NET](/v1/guias/sdk-dotnet): instala el SDK que incluye el verificador de firma. - [Seguimiento de una operación](/v1/guias/consulta-operacion): confirma el estado de una operación si dudas de un evento. --- # SDKs Bibliotecas oficiales para .NET, Node.js, Python, Java y PHP que llaman a la API por ti y resuelven la idempotencia, los reintentos y los webhooks. Puedes integrarte con nuestros servicios de facturación desde tu propio lenguaje con nuestros SDK oficiales, que instalas con el gestor de paquetes que ya usas. Trabajas con los mismos endpoints y las mismas respuestas que documentan las guías, ya convertidas en objetos de tu lenguaje, y te despreocupas de la parte donde más errores se cometen: reutilizar la `Idempotency-Key`, reintentar sin duplicar comprobantes y verificar la firma de los webhooks. En esta página comparas los cinco SDK, ves qué hacen por ti y qué endpoints cubren, y encuentras el enlace a la guía de tu lenguaje. ## Antes de empezar - [ ] Una API Key de pruebas. Si todavía no tienes una, crea tu sandbox como se explica en [Sandbox de pruebas](/v1/guias/sandbox); el alta tarda unos 10 minutos. - [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier IP. En producción, la IP de salida se registra en **Cuenta > IP permitidas** ([como](/v1/guias/sandbox#si-tu-ip-cambia)). - [ ] El entorno de tu lenguaje, en la versión mínima que indica la [Comparativa](#comparativa), con su gestor de paquetes (NuGet, npm, pip, Composer, Maven o Gradle). ## Comparativa La columna **Versión** indica la versión actual de cada SDK. | Lenguaje | Paquete | Versión mínima del lenguaje | Instalación | Versión | Registro / repositorio | Guía | |---|---|---|---|---|---|---| | .NET | `Ecuafact.Sdk` (+ `Ecuafact.Sdk.Core` para inyección de dependencias) | .NET Framework 4.6.1 o cualquier .NET compatible con `netstandard2.0`; probado en .NET 10 | `dotnet add package Ecuafact.Sdk` (y `dotnet add package Ecuafact.Sdk.Core` si usas inyección de dependencias) | `1.0.1` en ambos paquetes | [NuGet](https://www.nuget.org/packages/Ecuafact.Sdk) | [SDK .NET](/v1/guias/sdk-dotnet) | | Node.js | `@ecuafact/sdk` | Node.js 18 (módulo ES) | `npm install @ecuafact/sdk` | `1.0.1` | [npm](https://www.npmjs.com/package/@ecuafact/sdk) | [SDK Node.js](/v1/guias/sdk-node) | | Python | `ecuafact` | Python 3.10 | `pip install ecuafact` | `1.0.1` | [PyPI](https://pypi.org/project/ecuafact/) | [SDK Python](/v1/guias/sdk-python) | | Java | `com.ecuafact:sdk` | Java 17 | Dependencia Maven/Gradle `com.ecuafact:sdk:1.0.1` | `1.0.1` | [Maven Central](https://central.sonatype.com/artifact/com.ecuafact/sdk) | [SDK Java](/v1/guias/sdk-java) | | PHP | `ecuafact/sdk` | PHP 8.2 con `ext-curl` | `composer require ecuafact/sdk` | `v1.0.1` | [GitHub](https://github.com/Ecuanexus/ecuafact-sdk-php) / [Packagist](https://packagist.org/packages/ecuafact/sdk) | [SDK PHP](/v1/guias/sdk-php) | ## Qué hace el SDK por ti La tabla muestra lo que puedes dejar en manos de nuestros SDK y lo que tendrías que programar tú si consumes la API por HTTP directo. | Tarea | Con el SDK | Por HTTP directo | |---|---|---| | Autenticación | Configuras la API Key una vez, o el SDK la lee de `ECUAFACT_API_KEY`. Viaja en `X-Api-Key` en cada llamada y no aparece al imprimir el cliente ni sus opciones. | Agregas la cabecera en cada petición. | | URL base | La pasas una vez, sin `/v1`, o el SDK la lee de `ECUAFACT_BASE_URL`. El SDK no tiene una opción de ambiente; trabajas en pruebas o en producción según la URL que configuras. | Construyes cada ruta. | | `Idempotency-Key` | Si no la pasas, el SDK genera una, la reutiliza en sus reintentos y te la devuelve. Antes de enviarla, comprueba la misma regla que aplica la API: de 1 a 128 caracteres, solo letras, dígitos y `- _ . : /`. | La generas, la guardas y la reenvías tú. | | Reintentos | Puedes enviar sin preocuparte por los cortes de red: el SDK reintenta por ti los estados 408, 425, 500, 502, 503 y 504 y los errores de red, con 3 intentos en total por defecto, y respeta `Retry-After`. Solo reintenta operaciones idempotentes: `GET` y `POST`/`PUT` con `Idempotency-Key`; un `POST` o `PUT` sin clave, como la actualización del perfil, no se reintenta. El cambio de logo es la excepción en .NET y Python, que lo reintentan aunque no lleva clave porque subir el mismo archivo deja el perfil igual; en Node.js, Java y PHP no se reintenta. Puedes configurar los estados que se reintentan, la espera base, el backoff lineal o exponencial, la variación aleatoria y el tope de tiempo total. | Implementas la espera y el límite de intentos. | | Límite de solicitudes y cupo | El 429 por límite de solicitudes, que trae el `codEstado` 5005 (`limite_solicitudes`), se reintenta por defecto: el SDK espera lo que indica `Retry-After` y repite la solicitud. Si prefieres manejarlo tú, desactiva `RetryRateLimited` y el SDK lanza una excepción con la espera sugerida. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), **nunca** se reintenta. | Distingues el 5005 del 4004 leyendo `codEstado`. | | Importes | Usa tipos exactos, como `decimal` en .NET, `BigDecimal` en Java y `Decimal` en Python; en Node.js y PHP aceptas `number` o texto decimal. Los envía como número JSON sin pérdida de precisión. | Cuidas el redondeo y el formato del número. | | Errores | Puedes capturar una excepción por categoría (autenticación, validación, no encontrado, conflicto, límite, cupo, servidor, conexión, timeout, respuesta ilegible, respuesta demasiado grande, configuración y webhook). Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción conserva la `Idempotency-Key` de la solicitud y, según el lenguaje, su identificador de correlación; repite la emisión con esa misma clave y no se duplica el comprobante. Cada una trae el `codEstado` numérico, el `estado`, `msgError`, `errores` con el detalle, `estadoHttp`, `correlationId` con el valor de `X-Correlation-Id`, `idempotencyKey`, `retryAfter` y `esReintentable`. Los códigos del [catálogo](/v1/guias/errores#catalogo-de-codestado) están como constantes con nombre, por ejemplo `CodEstado.ComprobanteInvalido` (3002). | Lees el JSON de error y las cabeceras. | | Respuestas | Recibes objetos tipados, con los mismos campos de la respuesta JSON. La emisión y el seguimiento usan la misma forma, con `codEstado`, `errores`, `numeroDocumento`, `referenciaExterna`, `fhRecibido` y `fhAutorizacion`. El `estado` llega también como enum (`EstadoOperacion`) y el `tipoDocumento` como `TipoComprobante`; un estado que el SDK no reconoce se lee como `Desconocido`, y un tipo de comprobante desconocido, como `null`. Además tienes `esFinal` y `esAutorizado`. | Interpretas el JSON y comparas texto. | | Seguimiento | Si prefieres esperar el resultado en tu código, puedes usar el método opcional `esperarResultado`, que consulta la operación hasta un estado final o hasta un tiempo máximo. También puedes recibir el resultado por webhooks. | Escribes el bucle de consulta. | | Webhooks | Puedes verificar `Ecuafact-Signature` o las cabeceras de Standard Webhooks sobre el cuerpo crudo (texto o bytes), con varios secretos si necesitas rotarlos, y recibes el evento tipado. | Calculas el HMAC-SHA256, comparas en tiempo constante y parseas el JSON. | | Logo del perfil | `actualizarLogo` arma la petición `multipart/form-data` por ti. | Construyes el multipart. | | Varios contribuyentes | Si trabajas con varios contribuyentes, `para(identificacion)` te da una vista fija por contribuyente con todos los métodos que dependen de la identificación. | Cambias la ruta en cada llamada. | | Opciones por llamada | `RequestOptions` cambia en una sola llamada el tiempo por intento, el tope total, el `X-Correlation-Id` y los reintentos. La forma de cancelar una llamada depende del lenguaje. | Configuras cada petición. | | Información adicional | Puedes enviar un dato tuyo en la cabecera opcional `X-Additional-Info`, en todas tus llamadas o en una sola, como se explica en [Información adicional](#informacion-adicional). | Agregas la cabecera tú. | | Estado del servicio y catálogos | Consultas el estado público del servicio, sin API Key, y los catálogos del SRI como objetos tipados. Los nombres están en [Nombres equivalentes](#nombres-equivalentes). | Armas las peticiones y lees el JSON. | | Armar comprobantes | Puedes usar el constructor opcional `ComprobanteBuilder`, que arma la estructura de los seis tipos con los valores que le das, sin calcular totales ni completar valores por defecto: la API calcula y valida. | Escribes el JSON. | | Conexión | Te deja configurar el proxy, TLS y el tiempo de conexión. Cada lenguaje usa sus propias opciones, que están en la fila **Conexión** de [Nombres equivalentes](#nombres-equivalentes). | Configuras tu cliente HTTP. | ## Cuándo usar SDK o HTTP directo Te recomendamos nuestro **SDK** si tu lenguaje está en la tabla y puedes agregar dependencias a tu proyecto. Te conviene consumir la API por **HTTP directo** en cualquiera de estos casos: - Tu lenguaje no tiene SDK (Go, Ruby o Delphi, por ejemplo) o tu plataforma no te permite agregar paquetes. - Necesitas un endpoint que tu SDK no cubre; la lista está en [Cobertura](#cobertura). - Quieres controlar cada petición, por ejemplo para medirla con tus propias métricas o para reintentar de una forma que el SDK no permite configurar. Cada guía de endpoint trae ejemplos HTTP en cURL, .NET, Python, Node.js, PHP y Java; si eliges este camino, empieza por [Primeros pasos](/v1/guias/primeros-pasos). Si en cambio no quieres escribir código, puedes emitir con el [CLI de Ecuafact](/v1/guias/cli) desde la terminal o desde un script, a partir de archivos JSON, CSV o Excel. ## Ejemplo Este ejemplo emite una factura con cada SDK. El archivo `comprobante.json` contiene la [Estructura del comprobante](/v1/guias/emision-01), y cada guía de SDK lo trae completo en su quickstart. La API responde `202 Accepted` con el `estado` `recibido`, el `codEstado` 1001 o 1002 y un `idOperacion` para hacer el [seguimiento](/v1/guias/consulta-operacion). Con 1001 todavía no hay clave de acceso y `claveAcceso` es `null`; con 1002 ya viene, así que tu código debe aceptar los dos valores. Si repites la emisión con la misma `Idempotency-Key` y el mismo cuerpo, la respuesta trae el mismo `idOperacion` y el estado actual de la operación, y no se crea otro comprobante. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```csharp-sdk using System.Text.Json; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); FacturaRequest comprobante = JsonSerializer.Deserialize( await File.ReadAllTextAsync("comprobante.json"))!; EmisionResultado r = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001"); Console.WriteLine($"{r.Admission.Estado} {r.Admission.IdOperacion}"); ``` ```python-sdk import json import os from ecuafact import EcuafactClient, EcuafactClientOptions, FacturaRequest with open("comprobante.json", encoding="utf-8") as archivo: comprobante = FacturaRequest.model_validate(json.load(archivo)) with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: r = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001") print(r.admission.estado, r.admission.cod_estado, r.admission.id_operacion) ``` ```javascript-sdk // Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs import { readFile } from "node:fs/promises"; import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const comprobante = JSON.parse(await readFile("comprobante.json", "utf8")); const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001"); console.log(r.admission.estado, r.admission.codEstado, r.admission.idOperacion); ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001'); echo $r->admission->estado . ' ' . $r->admission->codEstado . ' ' . $r->admission->idOperacion . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.contracts.FacturaRequest; import com.fasterxml.jackson.databind.ObjectMapper; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); FacturaRequest comprobante = new ObjectMapper() .readValue(Files.readString(Path.of("comprobante.json")), FacturaRequest.class); EmisionResultado r = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001"); System.out.println(r.admission().estado() + " " + r.admission().codEstado() + " " + r.admission().idOperacion()); ``` `0123456789001` es la identificación de ejemplo de los [datos de prueba](/v1/guias/datos-de-prueba). En tu código usa la que devuelve tu [contexto](/v1/guias/consulta-contexto). ### Ejemplos completos En [Ecuanexus/ecuafact-api-ejemplos](https://github.com/Ecuanexus/ecuafact-api-ejemplos) encuentras ejemplos listos para ejecutar en los cinco lenguajes, cada uno en dos variantes: con el SDK y con HTTP directo. Cada variante trae un script de consola por tarea (contexto, validar, emitir, seguir, descargar el RIDE y el XML, consultas al SRI, verificar la firma de un webhook y manejo de errores) y una mini aplicación web que emite una factura de prueba y recibe webhooks. Usan el ambiente de pruebas y toman tu contribuyente del contexto, así que funcionan con tu sandbox sin editar nada. ## Información adicional Puedes enviar en la cabecera `X-Additional-Info` un dato tuyo, como la versión de tu ERP o la sucursal que emite, para que ubiquemos tus solicitudes cuando nos pidas soporte. Configúrala en el cliente para que viaje en cada solicitud, o cámbiala en una sola llamada con las opciones por llamada. Si una llamada no indica valor, usa el del cliente, y si le pasas un valor vacío, esa llamada sale sin la cabecera. La API la asocia a tu solicitud y no cambia la respuesta. Es la única cabecera propia que admiten nuestros SDK. Las reglas del valor están en [Límites](/v1/guias/limites#cabeceras) y el detalle de cada SDK en su guía: [.NET](/v1/guias/sdk-dotnet#informacion-adicional), [Python](/v1/guias/sdk-python#informacion-adicional), [Node.js](/v1/guias/sdk-node#informacion-adicional), [PHP](/v1/guias/sdk-php#informacion-adicional) y [Java](/v1/guias/sdk-java#informacion-adicional). ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!, AdditionalInfo = "erp=MiERP/4.2; sucursal=001" }); Contexto contexto = await client.GetContextoAsync(opciones: new RequestOptions { AdditionalInfo = "erp=MiERP/4.2; lote=42" }); Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}"); ``` ```python-sdk import os from ecuafact import EcuafactClient, EcuafactClientOptions, RequestOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], additional_info="erp=MiERP/4.2; sucursal=001", )) as client: contexto = client.get_contexto(opciones=RequestOptions(additional_info="erp=MiERP/4.2; lote=42")) print(f"Contribuyentes: {len(contexto.contribuyentes or [])}") ``` ```javascript-sdk import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY, additionalInfo: "erp=MiERP/4.2; sucursal=001" }); const contexto = await client.getContexto({ additionalInfo: "erp=MiERP/4.2; lote=42" }); console.log(`Contribuyentes: ${contexto.contribuyentes.length}`); ``` ```php-sdk getContexto(new RequestOptions(additionalInfo: 'erp=MiERP/4.2; lote=42')); echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL; ``` ```java-sdk import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.RequestOptions; import com.ecuafact.sdk.contracts.Contexto; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")) .additionalInfo("erp=MiERP/4.2; sucursal=001")); Contexto contexto = client.getContexto(RequestOptions.create().additionalInfo("erp=MiERP/4.2; lote=42")); System.out.println("Contribuyentes: " + contexto.contribuyentes().size()); ``` Si el valor tiene tildes, `ñ`, saltos de línea, espacios al inicio o al final o más de 256 caracteres, el SDK lanza `EcuafactConfigurationException` sin llamar a la API. ## Cobertura La tabla muestra qué operaciones cubre cada SDK. Python y PHP usan un tiempo máximo en lugar de cancelación de llamadas. Los nombres exactos de cada método están en la guía de tu lenguaje. | Operación | Endpoint | .NET | Node.js | Python | Java | PHP | |---|---|---|---|---|---|---| | Contexto | `GET /v1/contexto` | Sí | Sí | Sí | Sí | Sí | | Emitir | `POST /v1/contribuyentes/{identificacion}/{tipo}` (`{tipo}`: `facturas`, `liquidaciones-compra`, `notas-credito`, `notas-debito`, `guias-remision` o `retenciones`); la ruta sale de la clase del request (.NET, Python, Java, PHP) o del método por tipo (Node.js) | Sí | Sí | Sí | Sí | Sí | | Seguimiento | `GET /v1/operaciones/{idOperacion}` | Sí | Sí | Sí | Sí | Sí | | Listado de operaciones | `GET /v1/operaciones` | Sí | Sí | Sí | Sí | Sí | | Descargar RIDE / XML | `GET .../comprobantes/{claveAcceso}/ride` y `/xml` | Sí | Sí | Sí | Sí | Sí | | Cupo | `GET /v1/consumo` | Sí | Sí | Sí | Sí | Sí | | Perfil del emisor (leer y actualizar) | `GET`/`PUT /v1/contribuyentes/{identificacion}/perfil` | Sí | Sí | Sí | Sí | Sí | | Logo del perfil | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | Sí | Sí | Sí | Sí | Sí | | Consultas SRI (5 endpoints) | `GET /v1/consultas/...` | Sí | Sí | Sí | Sí | Sí | | Verificar firma de webhook | - (local) | Sí | Sí | Sí | Sí | Sí | | Evento de webhook tipado y varios secretos | - (local) | Sí | Sí | Sí | Sí | Sí | | Verificar con `Ecuafact-Signature` o con Standard Webhooks | - (local) | Sí | Sí | Sí | Sí | Sí | | Estado del servicio | `GET /estado` (sin API Key) | Sí | Sí | Sí | Sí | Sí | | Comprobación de salud | `GET /salud` (sin API Key) | Sí | Sí | Sí | Sí | Sí | | Catálogos del SRI | `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}` | Sí | Sí | Sí | Sí | Sí | | Esperar resultado | `GET /v1/operaciones/{idOperacion}` en bucle | Sí | Sí | Sí | Sí | Sí | | Opciones por llamada (`RequestOptions`) | Todos los endpoints | Sí | Sí | Sí | Sí | Sí | | Cancelar una llamada | Todos los endpoints | Sí (`CancellationToken`) | Sí (`signal`) | No (usa `timeout`) | Sí (`*Async` + `cancel`) | No (usa `timeout`) | | Constructores opcionales de comprobantes (sin cálculo ni validación de negocio local) | - (local) | Sí | Sí | Sí | Sí | Sí | Los SDK envían los comprobantes como JSON. Si quieres enviar el XML del SRI, usa HTTP directo, como se explica en [Emisión](/v1/guias/emision#cuerpo-json-o-xml). Los cinco SDK incluyen métodos para listar operaciones; los nombres exactos están en la guía de tu lenguaje. Para el estado del servicio y los catálogos, cada guía tiene una sección **Estado del servicio y catálogos**, por ejemplo la de [SDK Node.js](/v1/guias/sdk-node#estado-del-servicio-y-catalogos). Las respuestas y sus campos son los de [Estado del servicio](/v1/guias/estado-del-servicio) y [Catálogos](/v1/guias/catalogos#consultar-los-catalogos-por-api). Los SDK verifican la firma de los webhooks que recibes. Los destinos de webhooks no se administran con los SDK: créalos y gestiónalos desde el Portal del Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP o con la API REST, como se explica en [Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api). Para listar operaciones también puedes usar el CLI (`ecuafact operaciones listar`) o HTTP directo, con las rutas y los ejemplos de [Listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente). En .NET, igual que la API tiene un endpoint por tipo de documento, hay un request por tipo (`FacturaRequest`, `LiquidacionCompraRequest`, `NotaCreditoRequest`, `NotaDebitoRequest`, `GuiaRemisionRequest` y `RetencionRequest`), y `EmitirAsync` y `ValidarAsync` eligen la ruta por el tipo del request que entregas. El cuerpo HTTP no lleva ningún campo de tipo; la validación usa la misma ruta seguida de `/validar`. Los detalles están en [SDK .NET](/v1/guias/sdk-dotnet). En PHP pasa igual: cada tipo tiene su clase (`FacturaRequest`, `LiquidacionCompraRequest`, `NotaCreditoRequest`, `NotaDebitoRequest`, `GuiaRemisionRequest` y `RetencionRequest`, con su `Info*` y sus líneas), y `emitir`, `emitirEn`, `validar` y `validarEn` eligen la ruta por la clase que entregas. El cuerpo no lleva ningún campo de tipo ni hay opción de tipo en la llamada. Los detalles están en [SDK PHP](/v1/guias/sdk-php#tipo-de-comprobante-y-ruta). En Node.js hay un método por tipo en lugar de una clase que decide la ruta: `emitirFactura`, `emitirLiquidacionCompra`, `emitirNotaCredito`, `emitirNotaDebito`, `emitirGuiaRemision` y `emitirRetencion`, cada uno con su variante `...En` (`emitirFacturaEn`) y su `validar` correspondiente; los tipos `FacturaRequest`, `LiquidacionCompraRequest` y los demás describen el cuerpo. Los detalles están en [SDK Node.js](/v1/guias/sdk-node#tipo-de-comprobante-y-ruta). En Python y Java también hay una clase por tipo (`FacturaRequest`, `LiquidacionCompraRequest`, `NotaCreditoRequest`, `NotaDebitoRequest`, `GuiaRemisionRequest` y `RetencionRequest`), y `emitir`, `emitir_en` / `emitirEn`, `validar` y `validar_en` / `validarEn` eligen la ruta por la clase que entregas; el cuerpo tampoco lleva campo de tipo. Los detalles están en [SDK Python](/v1/guias/sdk-python#tipo-de-comprobante) y [SDK Java](/v1/guias/sdk-java#ruta-de-emision-por-tipo-de-comprobante). ## Nombres equivalentes Entre los cinco SDK cambian la convención de nombres y la unidad de tiempo que usa cada lenguaje. Usa esta tabla para pasar un ejemplo de un lenguaje a otro. | Concepto | .NET | Java | Node.js | Python | PHP | |---|---|---|---|---|---| | Esperar resultado | `EsperarResultadoAsync(id, intervalo?, maximo?)` (`TimeSpan`) | `esperarResultado(id, intervalo, maximo)` (`Duration`) | `esperarResultado(id, { intervaloMs, maximoMs, signal })` | `esperar_resultado(id, intervalo=5.0, maximo=120.0)` (segundos) | `esperarResultado($id, $intervalo = 5.0, $maximo = 120.0)` (segundos) | | Comprobar salud (`GET /salud`) | `SaludAsync()` | `obtenerSalud()` | `getSalud()` | `get_salud()` | `obtenerSalud()` | | Estado del servicio (`GET /estado`) | `ObtenerEstadoServicioAsync()` | `obtenerEstadoServicio()` | `getEstadoServicio()` | `get_estado_servicio()` | `obtenerEstadoServicio()` | | Índice de catálogos | `ListarCatalogosAsync()` | `listarCatalogos()` | `listarCatalogos()` | `listar_catalogos()` | `listarCatalogos()` | | Catálogo por clave | `ObtenerCatalogoAsync(nombre)` | `obtenerCatalogo(nombre)` | `getCatalogo(nombre)` | `get_catalogo(nombre)` | `obtenerCatalogo($nombre)` | | Subir logo | `ActualizarLogoAsync(...)` | `actualizarLogo(...)` | `actualizarLogo(...)` | `actualizar_logo(...)` | `actualizarLogo(...)` | | Evento de webhook | `WebhookEvent.Construir(secretos, cabecera, cuerpo)` | `WebhookEvent.construir(secretos, cabecera, cuerpo)` | `construirEvento(secretos, cabecera, cuerpo)` | `construir_evento(secretos, cabecera, cuerpo)` | `WebhookEvent::construir($secretos, $cabecera, $cuerpo)` | | Tipo del evento | `evento.Tipo` | `evento.eventType()` | `evento.eventType` | `evento.event_type` | `$evento->eventType` | | Estado final / autorizado | `operacion.EsFinal` / `EsAutorizado` | `operacion.esFinal()` / `esAutorizado()` | `esFinal(operacion)` / `esAutorizado(operacion)` | `operacion.es_final` / `es_autorizado` | `$operacion->esFinal()` / `esAutorizado()` | | Estado tipado | `operacion.EstadoOperacion` | `estadoOperacion()` | `estadoOperacion(op)` | `estado_operacion` | `estadoOperacion()` | | Código del resultado | `operacion.CodEstado` | `operacion.codEstado()` | `operacion.codEstado` | `operacion.cod_estado` | `$operacion->codEstado` | | Código de una excepción | `error.CodEstado` | `error.codEstado()` | `error.codEstado` | `error.cod_estado` | `$error->codEstado` | | Constantes del catálogo | `CodEstado.ComprobanteInvalido` | `CodEstado.COMPROBANTE_INVALIDO` | `CodEstado.ComprobanteInvalido` | `CodEstado.COMPROBANTE_INVALIDO` | `CodEstado::COMPROBANTE_INVALIDO` | | No reintentar el 429 con el `codEstado` 5005 (`limite_solicitudes`), que se reintenta por defecto | `RetryRateLimited = false` | `retryRateLimited(false)` | `retryRateLimited: false` | `retry_rate_limited=False` | `retryRateLimited: false` | | Códigos reintentables | `RetryableStatusCodes` | `retryableStatusCodes(...)` | `retryableStatusCodes` | `retry_status_codes` | `retryableStatusCodes` | | Espera base | `RetryBaseDelay` | `retryBaseDelay(...)` | `retryBaseDelayMs` | `retry_base_delay_ms` | `retryBaseDelaySeconds` | | Backoff | `RetryBackoff.Linear` / `Exponential` | `RetryBackoff.LINEAR` / `EXPONENTIAL` | `"linear"` / `"exponential"` | `RetryBackoff.LINEAR` / `EXPONENTIAL` | `RetryBackoff::Linear` / `Exponential` | | Variación aleatoria | `RetryJitter` | `retryJitter(...)` | `retryJitterMs` | `retry_jitter_ms` | `retryJitterSeconds` | | Tiempo por intento (30 s por defecto) | `Timeout` | `timeout(Duration)` | `timeoutMs` | `timeout` (segundos) | `timeout` (segundos) | | Tope de tiempo total | `TotalTimeout` | `totalTimeout(...)` | `totalTimeoutMs` | `total_timeout` | `totalTimeoutSeconds` | | Información adicional (`X-Additional-Info`) | `AdditionalInfo` | `additionalInfo(String)` | `additionalInfo` | `additional_info` | `additionalInfo` | | Conexión (proxy, TLS) | `Handler` | `httpClient`, `proxy`, `sslContext`, `connectTimeout` | `dispatcher` | `http_client`, `proxy`, `verify`, `connect_timeout` | `proxy`, `caInfo`, `connectTimeout`, `transport` | | Espera sugerida en el error | `RetryAfter` (`TimeSpan?`) | `retryAfter()` (`Duration`) | `retryAfterMs` | `retry_after` (`timedelta`) | `retryAfter` (segundos) | | Reintentable | `EsReintentable` | `esReintentable()` | `esReintentable` | `es_reintentable` | `esReintentable` | | Cupo agotado | `EcuafactQuotaException` | `EcuafactQuotaException` | `EcuafactQuotaException` | `EcuafactQuotaException` | `EcuafactQuotaException` | | Opciones por llamada | `RequestOptions` (último parámetro `opciones`) | `RequestOptions.create()` (sobrecarga con `RequestOptions` al final) | objeto `RequestOptions` (último parámetro) | `opciones=RequestOptions(...)` | `?RequestOptions $opciones` (último argumento) | | Tiempo por intento en una llamada | `Timeout` (`TimeSpan`) | `timeout(Duration)` | `timeoutMs` | `timeout` (segundos) | `timeout` (segundos) | | Tope total de una llamada | `TotalTimeout` (`TimeSpan`) | `totalTimeout(Duration)` | `totalTimeoutMs` | `total_timeout` (segundos) | `totalTimeout` (segundos) | | Correlación propia | `CorrelationId` | `correlationId(...)` | `correlationId` | `correlation_id` | `correlationId` | | Sin reintentos en una llamada | `Reintentos = false` | `reintentos(false)` | `reintentos: false` | `reintentos=False` | `reintentos: false` | | Información adicional en una llamada | `AdditionalInfo` | `additionalInfo(String)` | `additionalInfo` | `additional_info` | `additionalInfo` | | Cancelar una llamada | `CancellationToken` | variante `*Async` y `cancel(true)` | `signal` (`AbortSignal`) | No hay: usa `timeout` y `total_timeout` | No hay: usa `timeout` y `totalTimeout` | | Constructor de comprobantes | `ComprobanteBuilder.Factura(ruc, estab, ptoEmi)` | `ComprobanteBuilder.factura(ruc, estab, ptoEmi)` | `ComprobanteBuilder.factura(ruc, estab, ptoEmi)` | `ComprobanteBuilder.factura(ruc, estab, pto_emi)` | `ComprobanteBuilder::factura($ruc, $estab, $ptoEmi)` | | Tarifa de una línea | `new Impuesto { Codigo = "2", CodigoPorcentaje = "4", Tarifa = 15m }` | `Tarifa.of("4", new BigDecimal("15"))` | `{ codigoPorcentaje: "4", tarifa: 15 }` | `Tarifa("4", 15)` o `("4", 15)` | `Tarifa::iva('4', 15)` | ## Siguientes pasos - [SDK .NET](/v1/guias/sdk-dotnet), [Node.js](/v1/guias/sdk-node), [Python](/v1/guias/sdk-python), [Java](/v1/guias/sdk-java) o [PHP](/v1/guias/sdk-php): instala el de tu lenguaje y ejecuta su quickstart, que va de la API Key al RIDE. - [Primeros pasos](/v1/guias/primeros-pasos): sigue el mismo flujo por HTTP directo, sin SDK. - [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI y verifica su firma con el SDK. --- # SDK .NET Biblioteca oficial para emitir comprobantes desde .NET, seguir su autorización, descargar el RIDE y verificar webhooks sin armar las llamadas HTTP. Si desarrollas en C# o en cualquier otro lenguaje de .NET, puedes integrarte con nuestros servicios de facturación usando nuestro SDK para .NET. Lo instalas desde NuGet y, en lugar de armar cada petición HTTP, llamas a métodos como `EmitirAsync` o `DescargarRideAsync`, que reciben y devuelven objetos tipados. Puedes reintentar sin miedo a duplicar comprobantes, porque el SDK reutiliza la `Idempotency-Key` en sus reintentos. Además, envía tu API Key en cada llamada, te indica si llegaste al límite de solicitudes o si se agotó tu cupo, y verifica la firma de los webhooks que te enviamos. Esta guía empieza con la instalación, la configuración del cliente y un quickstart que va de la API Key al RIDE en tres pasos. Después documenta cada método, los errores, los reintentos, la inyección de dependencias en ASP.NET Core y los constructores de comprobantes. Si todavía no decides entre el SDK y la API por HTTP directo, compáralos en [SDKs](/v1/guias/sdk). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan > `https://api-sandbox.mynexusapi.com`; cambia a `https://api.mynexusapi.com` > solo cuando emitas comprobantes reales. ## 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: ```text Instala el SDK .NET de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. 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/sdk-dotnet.md antes de escribir código; no inventes campos. Reutiliza el lenguaje, el gestor de paquetes y la estructura del proyecto; si no hay proyecto, crea uno mínimo. Instala con dotnet add package Ecuafact.Sdk. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Usa Ecuafact.Sdk.Core solo si el proyecto ya usa inyección de dependencias. 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 programa e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer. ``` ## Paquetes | Paquete | Versión | Uso | |---|---|---| | `Ecuafact.Sdk` | `1.0.1` | Contiene el cliente (`EcuafactClient`), los modelos, las excepciones, los estados tipados y la verificación de webhooks. Es el único que necesitas para empezar. | | `Ecuafact.Sdk.Core` | `1.0.1` | Registra el cliente con `AddEcuafactClient` en el contenedor de dependencias de ASP.NET Core o de un Worker Service. Es opcional. | Ambos paquetes se compilan para `netstandard2.0` y `net10.0`, así que funcionan en .NET 10, en .NET Core 2.0 o superior y en .NET Framework 4.6.1 o superior. Se distribuyen en [NuGet](https://www.nuget.org/packages/Ecuafact.Sdk). Esta guía documenta la versión `1.0.1`. ## Requisitos - [ ] El SDK de .NET instalado. Para comprobarlo, ejecuta `dotnet --version`, que debe responder con un número de versión. - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, crea tu sandbox como se explica en [Sandbox de pruebas](/v1/guias/sandbox). - [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier IP. En producción, la IP desde la que ejecutas el código debe estar en **Cuenta > IP permitidas**; si no lo está, la API responde 403 con el `codEstado` 3010 (`ip_no_autorizada`). ## Instalación Crea un proyecto de consola y agrega el paquete. ```bash dotnet new console -n EcuafactPrueba cd EcuafactPrueba dotnet add package Ecuafact.Sdk dotnet list package ``` La instalación funcionó si `dotnet list package` muestra `Ecuafact.Sdk` con la versión `1.0.1`. Si vas a usar inyección de dependencias, agrega también `Ecuafact.Sdk.Core`, como se explica en [Inyección de dependencias](#inyeccion-de-dependencias). ## Configuración Crea el cliente **una vez** y reutilízalo en toda la aplicación. Es seguro para uso concurrente y sirve para todos los [contribuyentes](/v1/guias/glosario) de tu API Key. ```csharp using Ecuafact.Sdk; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!, Identificacion = "0123456789001" // opcional: contribuyente por defecto }); Console.WriteLine(client); // EcuafactClient { BaseAddress = https://api-sandbox.mynexusapi.com/, ApiKey = *** } ``` Si no configuras `ApiKey`, el SDK lee la variable de entorno `ECUAFACT_API_KEY`, y si no configuras `BaseAddress` (ni tu `HttpClient` trae una), lee `ECUAFACT_BASE_URL`. Con las dos variables definidas basta `EcuafactClient.Create(new EcuafactClientOptions())`. Los nombres están en las constantes `EcuafactClientOptions.ApiKeyEnvironmentVariable` y `EcuafactClientOptions.BaseUrlEnvironmentVariable`. Eliges el ambiente con la URL que configuras, porque el SDK no tiene una opción aparte para eso. Usa `https://api-sandbox.mynexusapi.com/` para pruebas y `https://api.mynexusapi.com/` para producción, **sin** `/v1`, ya que el SDK agrega la versión a cada ruta. | Opción | Tipo | Valor por defecto | Descripción | |---|---|---|---| | `BaseAddress` | `Uri?` | `null` | URL base de la API, sin `/v1`. Si es `null`, usa la del `HttpClient` y, si tampoco existe, `ECUAFACT_BASE_URL`. Debe ser absoluta HTTPS, sin credenciales, query string ni fragmento. | | `ApiKey` | `string?` | `null` | Tu API Key; viaja en la cabecera `X-Api-Key`. Si es `null` o vacía, usa `ECUAFACT_API_KEY`. No puede tener espacios al inicio o al final ni caracteres de control. No aparece en `ToString()` ni en el depurador. | | `Identificacion` | `string?` | `null` | Contribuyente por defecto para `EmitirAsync(comprobante)` y `ValidarAsync(comprobante)`. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). Déjalo vacío si tu API Key maneja varios contribuyentes. | | `Timeout` | `TimeSpan` | `00:00:30` (30 s) | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta. Mayor que cero o `Timeout.InfiniteTimeSpan`. El valor por defecto está en `EcuafactClientOptions.DefaultTimeout`. Por llamada lo cambias con `RequestOptions.Timeout`. | | `UserAgent` | `string` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. | | `RetryTransientFailures` | `bool` | `true` | Reintenta fallos transitorios (ver [Reintentos](#idempotencia-y-reintentos)). `false` desactiva todo reintento. | | `MaxAttempts` | `int` | `3` | Intentos por solicitud, incluido el primero. Debe ser 1 o mayor. | | `RespectRetryAfter` | `bool` | `true` | Si la cabecera `Retry-After` pide una espera mayor que la calculada, espera ese tiempo (con el tope de `MaxRetryDelay`). | | `MaxRetryDelay` | `TimeSpan` | `00:01:00` (60 s) | Espera máxima entre reintentos. Con `TimeSpan.Zero` no hay tope. | | `RetryRateLimited` | `bool` | `true` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`), respetando `Retry-After` y `MaxRetryDelay`. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. | | `RetryableStatusCodes` | `ISet` | `408`, `425`, `500`, `502`, `503`, `504` | Estados HTTP que se reintentan, entre 100 y 599. Para el 429 usa `RetryRateLimited` (agregar 429 aquí tiene el mismo efecto). Los valores por defecto están en `EcuafactClientOptions.DefaultRetryableStatusCodes`. | | `RetryBaseDelay` | `TimeSpan` | `200 ms` | Espera base entre reintentos. | | `RetryBackoff` | `RetryBackoff` | `RetryBackoff.Linear` | `Linear`: base x intento (200, 400, 600 ms). `Exponential`: base x 2^(intento-1) (200, 400, 800 ms). | | `RetryJitter` | `TimeSpan` | `50 ms` | Variación aleatoria que se suma a cada espera: en el intento *n*, un valor al azar de 0 a `RetryJitter` x *n*. Evita que varios procesos reintenten al mismo tiempo. | | `TotalTimeout` | `TimeSpan?` | `null` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas. Al superarlo lanza `EcuafactTimeoutException`. | | `MaxResponseBytes` | `long?` | `33554432` (32 MiB) | Tamaño máximo, en bytes, de cada respuesta de la API. El SDK la lee por partes y la aborta al superarlo con `EcuafactResponseTooLargeException`. `null` o `0` quitan el tope; no admite negativos. Por llamada lo cambias con `RequestOptions.MaxResponseBytes`. | | `MaxFileResponseBytes` | `long?` | `104857600` (100 MiB) | Igual que `MaxResponseBytes`, pero para las descargas de archivos (`DescargarRideAsync` y `DescargarXmlAsync`). `null` o `0` quitan el tope. | | `ValidarAntesDeEmitir` | `bool` | `false` | Si es `true`, `EmitirAsync` llama antes a `/validar` y no emite cuando la API responde `valido: false` (lanza `EcuafactValidationException`). Cada emisión hace 2 peticiones. Ver [Validar antes de cada emisión](#validar-antes-de-cada-emision). | | `AdditionalInfo` | `string?` | `null` | Texto tuyo que viaja en la cabecera `X-Additional-Info` en cada solicitud a la API. Si es `null` o vacío, no se envía. Admite solo ASCII imprimible (0x20 a 0x7E), sin espacios al inicio o al final y hasta 256 caracteres; el detalle está en [Información adicional](#informacion-adicional). | | `Handler` | `HttpMessageHandler?` | `null` | Handler para proxy, certificados, TLS o tiempo de conexión (`SocketsHttpHandler.ConnectTimeout`). Lo usa `EcuafactClient.Create` y, con inyección de dependencias, entra como handler principal de `IHttpClientFactory`. El SDK no lo libera. No aplica si pasas tu propio `HttpClient` (ver [HttpClient propio, proxy y TLS](#httpclient-propio-proxy-y-tls)). | Las opciones se validan al crear el cliente, antes de cualquier llamada. `Create` y el constructor lanzan `EcuafactConfigurationException` en cualquiera de estos casos: - Falta la API Key o la URL. - La URL no es HTTPS, contiene credenciales, query string o fragmento, o termina en `/v1`. - La API Key tiene espacios al inicio o al final, o caracteres de control. - `MaxAttempts` es menor que 1. - `Timeout` o `TotalTimeout` no son mayores que cero. - `MaxRetryDelay`, `RetryBaseDelay` o `RetryJitter` son negativos. - `RetryableStatusCodes` trae un código fuera del rango de 100 a 599. - `MaxResponseBytes` o `MaxFileResponseBytes` son negativos. - `AdditionalInfo` no cumple sus reglas. El mensaje de la excepción nunca incluye la API Key ni el valor de `AdditionalInfo`. Además, el cliente guarda una copia de las opciones, así que cambiar tu instancia de `EcuafactClientOptions` después de crearlo no lo afecta. La configuración efectiva está en `client.Options`, y al imprimirla la API Key aparece como `***`. ## Quickstart: de la API Key al RIDE Este programa hace el flujo completo en el ambiente de pruebas: lee tu [contexto](/v1/guias/consulta-contexto), emite una factura, espera el resultado del SRI con el [seguimiento](/v1/guias/consulta-operacion) y descarga el [RIDE](/v1/guias/glosario), el PDF del comprobante. ### Paso 1. Guarda el comprobante Guarda este JSON como `comprobante.json` en la carpeta del proyecto. Es una factura a consumidor final, con el tipo de identificación `07` y la identificación `9999999999999`, que solo se admite en facturas de hasta 50.00. Factura 10.00 más el IVA del 15 %, que son 1.50, por un total de 11.50. No lleva `secuencial`, porque te asignamos el siguiente [secuencial](/v1/guias/glosario) de la serie `estab`-`ptoEmi`. El programa reemplaza `ruc` por el de tu contexto y `fechaEmision` por la fecha de hoy. ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "07", "identificacionComprador": "9999999999999", "razonSocialComprador": "CONSUMIDOR FINAL", "totalSinImpuestos": 10.00, "totalDescuento": 0.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "baseImponible": 10.00, "valor": 1.50 } ], "propina": 0.00, "importeTotal": 11.50, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 11.50 } ] }, "detalles": [ { "codigoPrincipal": "SERV-001", "descripcion": "Servicio de prueba", "cantidad": 1, "precioUnitario": 10.00, "descuento": 0.00, "precioTotalSinImpuesto": 10.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 10.00, "valor": 1.50 } ] } ] } ``` `estab` y `ptoEmi` deben ser un [establecimiento](/v1/guias/glosario) y un [punto de emisión](/v1/guias/glosario) de tu emisor; el sandbox crea el establecimiento `001` con el punto de emisión `001`. El detalle de cada campo está en [Factura](/v1/guias/emision-01). ### Paso 2. Escribe el programa Reemplaza el contenido de `Program.cs` por el código siguiente. El paso 4 usa `EsperarResultadoAsync`, un método **opcional** que consulta la operación cada 5 segundos hasta tener un resultado final o hasta 2 minutos. En producción puedes usar en cambio el flujo asíncrono, en el que emites, guardas el `idOperacion` y procesas el resultado cuando llega el [webhook](/v1/guias/webhooks), sin que tu proceso se quede esperando. ```csharp using System.Text.Json; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); try { // 1. Contexto: que contribuyentes puede usar tu API Key. Contexto contexto = await client.GetContextoAsync(); Contribuyente emisor = contexto.Contribuyentes!.First(c => c.PuedeEmitir); Console.WriteLine($"Emisor {emisor.Identificacion}"); // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador). FacturaRequest comprobante = JsonSerializer.Deserialize( await File.ReadAllTextAsync("comprobante.json"))!; comprobante.InfoTributaria!.Ruc = emisor.Identificacion; comprobante.Info!.FechaEmision = DateTime.UtcNow.AddHours(-5).ToString("dd/MM/yyyy"); // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key. EmisionResultado emision = await client.EmitirAsync( emisor.Identificacion!, comprobante, idempotencyKey: "FACTURA-2026-0001"); // CodEstado es 1001 (aun sin clave de acceso) o 1002 (con ClaveAcceso); acepta los dos. Console.WriteLine($"estado {emision.Admission.Estado} codEstado {emision.Admission.CodEstado} idOperacion {emision.Admission.IdOperacion}"); // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min). Operation operacion = await client.EsperarResultadoAsync(emision.Admission.IdOperacion); Console.WriteLine($"estado {operacion.Estado} codEstado {operacion.CodEstado} {operacion.MsgError}".TrimEnd()); foreach (string detalle in operacion.Errores) { Console.WriteLine($" - {detalle}"); } // 5. RIDE: solo existe cuando el comprobante esta autorizado. if (operacion.EsAutorizado) { ArchivoComprobante ride = await client.DescargarRideAsync(emisor.Identificacion!, operacion.ClaveAcceso!); await File.WriteAllBytesAsync("ride.pdf", ride.Contenido); Console.WriteLine($"RIDE guardado en ride.pdf; claveAcceso {operacion.ClaveAcceso}"); } else if (!operacion.EsFinal) { Console.WriteLine("Aun sin resultado: consulta mas tarde o espera el webhook."); } } catch (EcuafactApiException error) { Console.WriteLine($"HTTP {error.EstadoHttp} codEstado {error.CodEstado}: {error.MsgError}"); foreach (string detalle in error.Errores) { Console.WriteLine($" - {detalle}"); } Console.WriteLine($"X-Correlation-Id: {error.CorrelationId}"); } ``` ### Paso 3. Ejecuta y verifica ```bash dotnet run ``` Deberías ver algo como esto; los identificadores cambian en cada ejecución: ``` Emisor 0123456789001 estado recibido codEstado 1001 idOperacion 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f estado autorizado codEstado 2001 RIDE guardado en ride.pdf; claveAcceso 0710202601012345678900110010010000001231234567811 ``` El programa funcionó si ves `estado autorizado` y el ejemplo guardó el RIDE como `ride.pdf`. La tabla explica cada línea que puede imprimir. | Salida | Significado | Qué hacer | |---|---|---| | `estado recibido codEstado 1001` | La API aceptó la emisión y respondió `202 Accepted`. Todavía no es la autorización. La respuesta puede traer 1001, cuando aún no hay clave de acceso y `ClaveAcceso` es `null`, o 1002, cuando ya la trae; tu código debe aceptar los dos. Si repetiste la misma `Idempotency-Key` con el mismo cuerpo, recibes la misma operación. | Sigue con el seguimiento. Para emitir otra factura cambia `referenciaExterna` y la `Idempotency-Key`. | | `estado autorizado codEstado 2001` | El SRI autorizó el comprobante. `ClaveAcceso` trae la [clave de acceso](/v1/guias/glosario) real de 49 dígitos. | Descarga el RIDE o el XML. | | `estado rechazado codEstado 3001` | El SRI rechazó el comprobante. Es un rechazo fiscal, y las líneas `-` muestran el mensaje del SRI, que llega en `Errores`. | Corrige los datos y emite un comprobante nuevo con **nueva** `Idempotency-Key`, nueva `referenciaExterna` y un secuencial nuevo. | | `estado rechazado`, `rechazo_configuracion`, `error` o `cancelado` con otro `codEstado` | La operación terminó sin autorización. | Busca el `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion) y sigue lo que indica. | | `Aun sin resultado` | Pasaron 2 minutos y el `estado` sigue en `recibido`. | Vuelve a consultar más tarde o espera el [webhook](/v1/guias/webhooks). | | `HTTP 401 codEstado 3009` | La API Key no es válida. | Revisa `ECUAFACT_API_KEY`. | | `HTTP 422 codEstado 3002` | Falta un campo, un campo está mal formado o no se cumple una regla fiscal, por ejemplo totales que no cuadran. Las líneas `-` muestran el detalle de `Errores`. | Corrige el JSON; un 422 consume 1 documento como intento. | > [!NOTE] > Si ejecutas el programa otro día con la misma `Idempotency-Key`, la fecha de > hoy cambia el cuerpo y la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Usa una > `Idempotency-Key` y una `referenciaExterna` nuevas para cada factura nueva. Los valores posibles de `Estado` y `CodEstado` están en [Seguimiento de una operación](/v1/guias/consulta-operacion), en el [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado) y en [Estados tipados](#estados-tipados). ## Métodos Todos los métodos que llaman a la API son asíncronos y aceptan, después de sus parámetros, un `CancellationToken ct` opcional y un `RequestOptions? opciones` opcional, que se explica en [Opciones por llamada](#opciones-por-llamada). En las rutas `/v1/contribuyentes/...`, la identificación es siempre el valor `identificacion` que devuelve el contexto, que es la identificación completa del contribuyente y también el valor de `infoTributaria.ruc`. El SDK rechaza, sin llamar a la API, una identificación que no tenga de 5 a 13 dígitos (por ejemplo vacía, `.` o `..`), y lo mismo hace con una `claveAcceso`, un RUC o un número vacíos, de solo espacios, `.` o `..` en las descargas y las consultas. Igual que la API tiene un endpoint por tipo de documento, el SDK tiene un request por tipo de documento, y `EmitirAsync` y `ValidarAsync` eligen la ruta por el tipo del request que les pasas. El cuerpo HTTP es el request tal cual: no existe `infoTributaria.tipoDocumento` ni un modelo genérico de comprobante. | Request | Documento | Ruta de emisión | Ruta de validación | |---|---|---|---| | `FacturaRequest` | Factura | `POST /v1/contribuyentes/{identificacion}/facturas` | `POST /v1/contribuyentes/{identificacion}/facturas/validar` | | `LiquidacionCompraRequest` | Liquidación de compra | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra/validar` | | `NotaCreditoRequest` | Nota de crédito | `POST /v1/contribuyentes/{identificacion}/notas-credito` | `POST /v1/contribuyentes/{identificacion}/notas-credito/validar` | | `NotaDebitoRequest` | Nota de débito | `POST /v1/contribuyentes/{identificacion}/notas-debito` | `POST /v1/contribuyentes/{identificacion}/notas-debito/validar` | | `GuiaRemisionRequest` | Guía de remisión | `POST /v1/contribuyentes/{identificacion}/guias-remision` | `POST /v1/contribuyentes/{identificacion}/guias-remision/validar` | | `RetencionRequest` | Comprobante de retención | `POST /v1/contribuyentes/{identificacion}/retenciones` | `POST /v1/contribuyentes/{identificacion}/retenciones/validar` | Cada request contiene solo las propiedades de su esquema del contrato, con sus mismos nombres, tipos, nulabilidad y campos obligatorios (los obligatorios llevan el atributo informativo `[Obligatorio]`; el SDK no valida, lo hace la API). Todos comparten `InfoTributaria`, `Pago`, `Impuesto` y `CampoAdicional`. Cada tipo agrega su cuerpo propio: | Request | Información | Líneas | |---|---|---| | `FacturaRequest` | `InfoFactura` (incluye los nueve campos de exportación) | `Detalles`: `DetalleCompraVenta` | | `LiquidacionCompraRequest` | `InfoLiquidacionCompra` | `Detalles`: `DetalleCompraVenta` | | `NotaCreditoRequest` | `InfoNotaCredito` | `Detalles`: `DetalleNotaCredito` | | `NotaDebitoRequest` | `InfoNotaDebito` | `Motivos`: `Motivo` | | `GuiaRemisionRequest` | `InfoGuiaRemision` | `Destinatarios`: `Destinatario` con `DetalleGuia` | | `RetencionRequest` | `InfoComprobanteRetencion` | `DocsSustento`: `DocsSustento` con `ImpuestoDocSustento` y `RetencionLinea` | Los métodos `EmitirAsync` y `ValidarAsync` aceptan cualquiera de los seis requests (heredan de `ComprobanteRequestBase`, que no se puede extender fuera del SDK). Un argumento nulo lanza `ArgumentNullException` sin llamar a la API. | Método | Endpoint | Devuelve | |---|---|---| | `GetContextoAsync()` | `GET /v1/contexto` | `Contexto` (cliente y contribuyentes de tu API Key) | | `EmitirAsync(comprobante, idempotencyKey?)` | `POST /v1/contribuyentes/{Identificacion por defecto}/{ruta del tipo}` | `EmisionResultado` | | `EmitirAsync(identificacion, comprobante, idempotencyKey?)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` | | `ValidarAsync(comprobante)` | `POST /v1/contribuyentes/{Identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionResultado` (revisa `Valido`; ver [Validar sin emitir](#validar-sin-emitir)) | | `ValidarAsync(identificacion, comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionResultado` | | `GetOperacionAsync(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (seguimiento). Acepta `Guid` o, como extensión, un `string` con un UUID. | | `ConsultarOperacionAsync(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias del anterior) | | `EsperarResultadoAsync(idOperacion, intervalo?, maximo?)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída. Opcional; ver [Esperar el resultado](#esperar-el-resultado). | | `DescargarRideAsync(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | `ArchivoComprobante` (PDF) | | `DescargarXmlAsync(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | `ArchivoComprobante` (XML del comprobante autorizado) | | `GetConsumoAsync()` | `GET /v1/consumo` | `QuotaBucket` (cupo) | | `ListarOperacionesAsync(identificacion, desde?, hasta?, tipoDocumento?, buscar?, pagina?, tamanoPagina?)` | `GET /v1/operaciones` | `PaginaComprobantes` (ver [Listado de comprobantes emitidos](#listado-de-comprobantes-emitidos)) | | `SaludAsync()` | `GET /salud` | `EstadoServicio` (`Servicio` y `Estado`). No envía la API Key. | | `ObtenerEstadoServicioAsync()` | `GET /estado` | `EstadoPublico` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)). No envía la API Key. | | `ListarCatalogosAsync()` | `GET /v1/catalogos` | `Catalogos` | | `ObtenerCatalogoAsync(nombre)` | `GET /v1/catalogos/{nombre}` | `CatalogoDetalle` | | `GetPerfilAsync(identificacion)` | `GET /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` | | `ActualizarPerfilAsync(identificacion, cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` | | `ActualizarLogoAsync(identificacion, contenido, contentType, nombreArchivo)` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (PNG o JPEG, hasta 512 KB; ver [Logo del perfil](#logo-del-perfil)) | | `ConsultarContribuyenteAsync(identificacion, fusionar = true, fuente?)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta` | | `BuscarContribuyentesAsync(apellidos, nombres?, clase?, max?)` | `GET /v1/consultas/contribuyentes` | `IReadOnlyList` | | `ListarEstablecimientosAsync(ruc, filtro?)` | `GET /v1/consultas/establecimientos/{ruc}` | `EstablecimientosContribuyente` | | `ValidarIdentificacionAsync(numero)` | `GET /v1/consultas/identificacion/validar/{numero}` | `ValidacionIdentificacion` (revisa `Valido`) | | `DecodificarClaveAccesoAsync(claveAcceso)` | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | `ClaveAccesoDecodificada` | | `Para(identificacion)` | - (no llama a la API) | `IEcuafactContribuyente` fijado a un contribuyente | | `WebhookEvent.Construir(...)`, `WebhookEvent.ConstruirDesdeEntrega(...)`, `WebhookSignature.Verify(...)`, `WebhookSignature.VerificarEntrega(...)` y `StandardWebhookSignature.Verify(...)` (espacio de nombres `Ecuafact.Sdk.Webhooks`) | - (local) | `WebhookEvent` o `bool` (ver [Webhooks](#webhooks)) | `EsperarResultadoAsync` y la sobrecarga de `GetOperacionAsync` con `string` son métodos de extensión de `EcuafactClientExtensions` (espacio de nombres `Ecuafact.Sdk`), así que funcionan tanto sobre `EcuafactClient` como sobre `IEcuafactClient`. Algunos tipos de la respuesta traen datos que conviene conocer: - `EmisionResultado` trae `Admission`, `IdempotencyKey` (la clave usada) y `CorrelationId` (la cabecera `X-Correlation-Id`). `Admission` tiene los mismos campos que `Operation`, que se describen en [Esperar el resultado](#esperar-el-resultado). En una emisión aceptada, `Estado` es `recibido` y `CodEstado` es 1001 o 1002: con 1001, `ClaveAcceso` todavía es `null`, y con 1002 ya trae la clave de acceso. Tu código debe aceptar los dos valores. `UrlEstado` es la URL completa del seguimiento. - `ArchivoComprobante` trae `Contenido` (`byte[]`) y `ContentType`. Las descargas solo existen con el comprobante autorizado; ver [Descargar XML](/v1/guias/consulta-xml). - `QuotaBucket` trae `LimiteDocumentos`, `Reservados`, `Consumidos`, `Disponibles`, `VigenteHasta` y los campos `...Extra`, que se mantienen por compatibilidad y valen 0. Cada comprobante autorizado o rechazado consume un documento de tu cupo, y uno cancelado lo libera; el detalle está en [Consumo](/v1/guias/consumo). ## Validar sin emitir Antes de emitir puedes comprobar que un comprobante está bien armado con `ValidarAsync`. La validación aplica las mismas reglas que la emisión y recibe el mismo request del tipo, pero no emite nada, no consume cupo ni usa un número de la serie, y no necesita `Idempotency-Key`. Usa la misma ruta del tipo que la emisión, seguida de `/validar`. Te sirve sobre todo cuando generas comprobantes de forma automática, porque validas el lote completo, corriges lo que falle y emites después solo lo que pasó. Cada validación cuenta para tu [límite de solicitudes](/v1/guias/limite-de-request) por minuto. `ValidarAsync` devuelve un `ValidacionResultado` con seis propiedades: `Valido`, `CodEstado`, `MsgError`, `Errores`, `Advertencias` y `CorrelationId` (la cabecera `X-Correlation-Id`). Si el comprobante cumple las reglas, `Valido` es `true`, `CodEstado` es `null` y `Errores` viene vacía. `Advertencias` trae los avisos que no impiden emitir, por ejemplo que la firma incluida en un XML se ignora, y viene vacía si no hay ninguno. Si el comprobante no cumple las reglas, el método no lanza una excepción: `Valido` es `false`, `CodEstado` es 3002 (`CodEstado.ComprobanteInvalido`) y `Errores` trae el mismo detalle que recibirías al emitirlo, con la ruta del campo que falla. Los demás errores se comportan igual que en cualquier otro método y lanzan la excepción que corresponde (ver [Errores](#errores)). Por ejemplo, si el contribuyente, su RUC o el tipo de comprobante no están habilitados para tu API Key, recibes una `EcuafactAuthException` con el `CodEstado` 3011 (`acceso_denegado`). Como validar no tiene efectos, el SDK reintenta los fallos transitorios igual que en una consulta. ```csharp // Program.cs de un proyecto creado con: dotnet new console using System.Text.Json; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); Contexto contexto = await client.GetContextoAsync(); Contribuyente emisor = contexto.Contribuyentes!.First(c => c.PuedeEmitir); FacturaRequest comprobante = JsonSerializer.Deserialize( await File.ReadAllTextAsync("comprobante.json"))!; comprobante.InfoTributaria!.Ruc = emisor.Identificacion; comprobante.Info!.FechaEmision = DateTime.UtcNow.AddHours(-5).ToString("dd/MM/yyyy"); ValidacionResultado validacion = await client.ValidarAsync(emisor.Identificacion!, comprobante); if (validacion.Valido) { Console.WriteLine("Comprobante valido: ya puedes emitirlo con EmitirAsync."); } else { Console.WriteLine($"Comprobante invalido (codEstado {validacion.CodEstado}):"); foreach (string error in validacion.Errores) { Console.WriteLine($" - {error}"); } } ``` Con el `comprobante.json` del [Quickstart](#quickstart-de-la-api-key-al-ride), el programa imprime `Comprobante valido`. Si cambias el `valor` de un impuesto para que no coincida con su base y su tarifa, imprime el error `$.detalles[0].impuestos[0].valor: Valor de impuesto no coincide con base y tasa.` Un comprobante válido no garantiza que la emisión se acepte: la validación no comprueba tu cupo ni si ya emitiste ese comprobante. El detalle está en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). También puedes validar desde la vista de un contribuyente con `client.Para(identificacion).ValidarAsync(comprobante)`. ### Validar antes de cada emisión Es opcional y viene apagada. Con `ValidarAntesDeEmitir = true` en `EcuafactClientOptions`, `EmitirAsync` llama primero a `/validar` y emite solo si la API da el comprobante por válido; son 2 peticiones por emisión. Con el valor por defecto (`false`) `EmitirAsync` envía directo, hace 1 petición y, si el comprobante no cumple, la API responde 422 y el SDK lanza `EcuafactValidationException` con `Errores`. Con la opción activa, si `Valido` es `false` el SDK lanza esa misma excepción (422, `CodEstado` 3002) sin emitir ni consumir cupo, y las advertencias de la validación quedan en `EmisionResultado.Advertencias` (vacía si no hubo). Con inyección de dependencias, la clave de configuración es `ValidarAntesDeEmitir`. ```csharp using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!, ValidarAntesDeEmitir = true }); ``` ## Esperar el resultado Después de emitir, el comprobante queda **recibido**, que es lo que significa el `202 Accepted`, y el SRI responde en segundos o en minutos. Puedes conocer el resultado de dos formas. | Forma | Cómo | Cuándo usarla | |---|---|---| | Seguimiento | `GetOperacionAsync(idOperacion)` una vez, o `EsperarResultadoAsync(idOperacion)` en bucle. | Scripts, procesos por lotes o pantallas que esperan al usuario. | | [Webhooks](#webhooks) | Te avisamos en tu URL cuando hay resultado. | Producción con muchos comprobantes: no ocupas tu proceso esperando. | `EsperarResultadoAsync(idOperacion, intervalo?, maximo?, ct, opciones)` consulta `GET /v1/operaciones/{idOperacion}` hasta que `EsFinal` es `true` o hasta que pasa `maximo`, y devuelve la última `Operation` leída. No lanza una excepción al agotar el tiempo, así que revisa `EsFinal` en el resultado. | Parámetro | Tipo | Valor por defecto | Descripción | |---|---|---|---| | `idOperacion` | `Guid` | - | El `Admission.IdOperacion` de la emisión. | | `intervalo` | `TimeSpan?` | 5 s (`EcuafactClientExtensions.IntervaloEsperaPorDefecto`) | Espera entre consultas. Mayor que cero; si no, lanza `ArgumentOutOfRangeException`. | | `maximo` | `TimeSpan?` | 120 s (`EcuafactClientExtensions.MaximoEsperaPorDefecto`) | Tiempo total de espera. No negativo; con `TimeSpan.Zero` consulta una sola vez. | | `ct` | `CancellationToken` | `default` | Cancela la espera; lanza `OperationCanceledException`. | | `opciones` | `RequestOptions?` | `null` | Se aplica a cada consulta (ver [Opciones por llamada](#opciones-por-llamada)). | Cada consulta cuenta para tu límite de solicitudes por minuto; por eso no conviene usar intervalos de menos de unos segundos. ```csharp // Program.cs de un proyecto creado con: dotnet new console using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); // Usa el idOperacion que devolvio tu emision. Guid idOperacion = Guid.Parse("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"); Operation operacion = await client.EsperarResultadoAsync( idOperacion, intervalo: TimeSpan.FromSeconds(10), maximo: TimeSpan.FromMinutes(5)); if (operacion.EsAutorizado) { Console.WriteLine($"Autorizado. claveAcceso {operacion.ClaveAcceso}"); } else if (operacion.EsFinal) { Console.WriteLine($"Sin autorizacion: estado {operacion.Estado}, codEstado {operacion.CodEstado}: {operacion.MsgError}"); foreach (string detalle in operacion.Errores) { Console.WriteLine($" - {detalle}"); } } else { Console.WriteLine($"Aun sin resultado ({operacion.Estado}): consulta mas tarde o espera el webhook."); } ``` `Operation` trae los campos de [Seguimiento de una operación](/v1/guias/consulta-operacion): `Estado`, `CodEstado`, `MsgError`, `Errores`, `IdOperacion`, `UrlEstado`, `Ambiente`, `TipoDocumento`, `NumeroDocumento`, `ReferenciaExterna`, `ClaveAcceso`, `FhRecibido` y `FhAutorizacion`, más las propiedades tipadas de la sección siguiente. `MsgError` es la descripción fija del código y es `null` mientras no hay error; el detalle, como el mensaje del SRI en un rechazo 3001 (`rechazo_sri`), llega en `Errores`. `FhRecibido` es el momento en que la API aceptó la emisión, y `FhAutorizacion`, el de la autorización del SRI, cuando existe. `Admission` tiene exactamente los mismos campos. ## Estados tipados `Operation`, `Admission` y `Comprobante` conservan los campos de la API (`Estado`, `CodEstado`, `TipoDocumento`) y agregan propiedades tipadas para comparar sin errores de escritura. Un valor que tu versión del SDK no conoce no rompe tu código, porque el estado se lee como `Desconocido` y el tipo de comprobante como `null`, mientras el texto original sigue en el campo `string`. | Propiedad | Tipo | Valores | |---|---|---| | `Operation.EstadoOperacion`, `Comprobante.EstadoOperacion`, `Admission.EstadoOperacion` | `EstadoOperacion` | `Recibido`, `Autorizado`, `Rechazado`, `RechazoConfiguracion`, `Error`, `Cancelado`, `Desconocido` | | `Operation.TipoComprobante`, `Comprobante.TipoComprobante` | `TipoComprobante?` | `Factura` (`01`), `LiquidacionCompra` (`03`), `NotaCredito` (`04`), `NotaDebito` (`05`), `GuiaRemision` (`06`), `Retencion` (`07`); `null` si el código no se conoce | | `Operation.EsFinal`, `Comprobante.EsFinal` | `bool` | `true` si `estado` es cualquier valor distinto de `recibido`: `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. | | `Operation.EsAutorizado`, `Comprobante.EsAutorizado` | `bool` | `true` si `estado` es `autorizado`. | | `WebhookEvent.Tipo` | `TipoEventoWebhook` | `DocumentoAutorizado`, `DocumentoRechazado`, `DocumentoFallido`, `OperacionRequiereAtencion`, `Desconocido` | Los enums están en `Ecuafact.Sdk.Contracts` (`TipoEventoWebhook`, en `Ecuafact.Sdk.Webhooks`). `EstadosApi.ParseEstadoOperacion`, `EstadosApi.ParseTipoComprobante` (devuelve `TipoComprobante?`) y `EstadosApi.TipoDocumento(tipo)` convierten entre texto y enum, y `EstadosApi.EsFinal(estado)` te dice si un estado es final. Los valores de `codEstado` están como constantes `int` en la clase `CodEstado`, por ejemplo `CodEstado.RechazoSri` (3001), `CodEstado.ComprobanteInvalido` (3002) o `CodEstado.LimiteSolicitudes` (5005), y `CodEstado.Estado(codigo)` devuelve el `EstadoOperacion` que corresponde al primer dígito, incluso para un código que tu versión del SDK todavía no conoce. Los valores de `estado` están en `EstadosPublicos`, por ejemplo `EstadosPublicos.Recibido`. ```csharp using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); Operation operacion = await client.GetOperacionAsync("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"); string accion = operacion.EstadoOperacion switch { EstadoOperacion.Autorizado => "Descarga el RIDE", EstadoOperacion.Rechazado when operacion.CodEstado == CodEstado.RechazoSri => "Corrige y emite un comprobante nuevo", EstadoOperacion.Recibido => "Consulta mas tarde", _ => $"Revisa codEstado {operacion.CodEstado}: {operacion.MsgError} {string.Join(" | ", operacion.Errores)}" }; Console.WriteLine($"{operacion.TipoComprobante?.ToString() ?? "Tipo no reconocido"}: {accion}"); ``` ## Webhooks Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle. Antes de procesar una entrega, verifica que te la enviamos nosotros con `WebhookEvent.ConstruirDesdeEntrega`, del espacio de nombres `Ecuafact.Sdk.Webhooks`. Cada entrega trae dos firmas, la cabecera `Ecuafact-Signature` y las cabeceras de [Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks), y este método acepta cualquiera de las dos. `WebhookEvent.ConstruirDesdeEntrega(secretos, cabeceras, cuerpo, tolerancia?)` recibe las cabeceras de la petición, ya sea como una función que devuelve el valor por nombre (`nombre => request.Headers[nombre]`) o como pares nombre-valor, y las comprueba contra el cuerpo **crudo**. Si alguna firma es válida, devuelve el evento tipado. Si ninguna coincide, está fuera de la tolerancia (300 s por defecto, `WebhookSignature.DefaultTolerance`) o el cuerpo no es un evento JSON, lanza `EcuafactWebhookException`. Los secretos se aceptan con o sin el prefijo `whsec_`. Si solo recibes la firma `Ecuafact-Signature` (`t=,v1=`), puedes usar `WebhookEvent.Construir(secretos, cabecera, cuerpo, tolerancia?)`, que verifica solo esa cabecera y se comporta igual. | Parámetro | Tipo | Descripción | |---|---|---| | `secretos` | `IEnumerable` o `string` | Secreto del destino, que ves al crearlo. Con una lista, la entrega es válida si coincide con cualquiera. | | `cabeceras` | `Func` o `IEnumerable>` | Cabeceras de la petición. En `Construir` se pasa en su lugar `cabecera`, un `string` con el valor de `Ecuafact-Signature` (nombre en `WebhookSignature.HeaderName`). | | `cuerpo` | `string` o `byte[]` | Cuerpo crudo, tal como llegó. | | `tolerancia` | `TimeSpan?` | Antigüedad máxima de la firma. Por defecto 300 s. | Con una lista de secretos puedes rotar el secreto sin rechazar entregas. Agrega el nuevo, publica tu aplicación y quita el anterior cuando las entregas lleguen firmadas con el nuevo, como se explica en [Rotación de secreto](/v1/guias/webhooks-firma#rotacion-de-secreto). El SDK no administra los destinos de webhooks, solo verifica la firma y construye el evento. Los destinos los creas, listas, pausas y rotas desde el Portal del Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP o con la API REST, como se explica en [Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api). El ejemplo siguiente usa ASP.NET Core con una minimal API. Guarda tu secreto en `ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en `ECUAFACT_WEBHOOK_SECRET_ANTERIOR`. ```csharp // Program.cs de un proyecto creado con: dotnet new web // Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run using Ecuafact.Sdk; using Ecuafact.Sdk.Webhooks; WebApplicationBuilder builder = WebApplication.CreateBuilder(args); WebApplication app = builder.Build(); string[] secretos = new[] { Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET"), Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET_ANTERIOR") }.OfType().Where(s => s.Length > 0).ToArray(); app.MapPost("/webhooks/ecuafact", async (HttpRequest request) => { using MemoryStream copia = new(); await request.Body.CopyToAsync(copia); byte[] cuerpoCrudo = copia.ToArray(); WebhookEvent evento; try { evento = WebhookEvent.ConstruirDesdeEntrega(secretos, nombre => request.Headers[nombre], cuerpoCrudo); } catch (EcuafactWebhookException) { return Results.Unauthorized(); } // Deduplica por EventTypeRaw + ResourceId antes de procesar y responde 2xx. switch (evento.Tipo) { case TipoEventoWebhook.DocumentoAutorizado: Console.WriteLine($"Autorizado {evento.IdOperacion} claveAcceso {evento.ClaveAcceso}"); break; case TipoEventoWebhook.DocumentoRechazado: Console.WriteLine($"Rechazo fiscal {evento.IdOperacion}: codEstado {evento.CodEstado} {string.Join(" | ", evento.Errores)}"); break; case TipoEventoWebhook.DocumentoFallido: Console.WriteLine($"No emitido {evento.IdOperacion}: estado {evento.Estado}, codEstado {evento.CodEstado}"); break; default: Console.WriteLine($"Evento {evento.EventTypeRaw} (prueba: {evento.Probe})"); break; } return Results.Ok(); }); app.Run(); ``` | Propiedad de `WebhookEvent` | Tipo | Descripción | |---|---|---| | `Tipo` | `TipoEventoWebhook` | `DocumentoAutorizado`, `DocumentoRechazado`, `DocumentoFallido`, `OperacionRequiereAtencion` o `Desconocido` (un tipo nuevo). | | `EventTypeRaw` | `string` | Texto original de `eventType` (`document.authorized`, `document.rejected`, `document.failed`, `operation.requires_attention`). | | `ResourceId` | `string?` | Recurso del evento: el `idOperacion` en los eventos `document.*`. Úsalo con `EventTypeRaw` para descartar entregas repetidas. | | `OccurredAtUtc` | `DateTimeOffset?` | Momento del evento (UTC). | | `IdOperacion` | `Guid?` | Operación de la emisión. | | `Estado` | `string?` | El mismo `estado` del seguimiento: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`, y `recibido` en el aviso `operation.requires_attention`. Su versión tipada es `EstadoOperacion`. | | `TipoDocumento` | `string?` | Tipo de comprobante (`01` a `07`), cuando el evento lo trae. | | `Ruc` | `string?` | Identificación del contribuyente emisor. Sirve para enrutar un destino compartido por varios contribuyentes; es `null` en el evento de prueba. | | `ClaveAcceso` | `string?` | Clave de acceso. En `document.failed` puede faltar. | | `CodEstado` | `int?` | Código numérico del resultado, por ejemplo 2001 en `document.authorized`, 3001 (`rechazo_sri`) en `document.rejected` o 4002 (`firma_no_valida`) en `document.failed`. Compáralo con las constantes de `CodEstado`. | | `MsgError` | `string?` | Descripción fija del código; `null` cuando no hay error. | | `Errores` | `IReadOnlyList` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacía si no hay detalle. | | `FhAutorizacion` | `DateTimeOffset?` | Fecha y hora de la autorización del SRI, cuando existe. | | `Probe` | `bool` | `true` en el evento de prueba que envía el botón **Probar** del portal (`operation.requires_attention`). | Si solo necesitas saber si la firma es válida, usa `WebhookSignature.VerificarEntrega(secretos, cabeceras, cuerpo, tolerancia?)`, que acepta cualquiera de las dos firmas, o `WebhookSignature.Verify(secretos, cabecera, cuerpo, tolerancia?)`, que comprueba solo `Ecuafact-Signature`. Los dos devuelven `bool` y no lanzan ante una firma o cabecera inválida; aceptan un secreto o una lista, y el cuerpo como `string` o `byte[]`. `StandardWebhookSignature.Verify(secreto, id, timestamp, firma, cuerpo, tolerancia?)` comprueba solo la firma de Standard Webhooks con los valores de `webhook-id`, `webhook-timestamp` y `webhook-signature`. > [!WARNING] > Verifica la firma sobre el cuerpo crudo, tal como llegó. Si deserializas y > vuelves a serializar el JSON, la firma no coincide. Cada verificación termina de una de estas maneras, y en todas las que no son válidas debes responder 401 sin procesar el evento. | Situación | `Construir` y `ConstruirDesdeEntrega` | `Verify` y `VerificarEntrega` | |---|---|---| | Firma válida | Devuelven el `WebhookEvent` tipado. | Devuelven `true`. | | Cuerpo alterado, aunque sea por un espacio | Lanzan `EcuafactWebhookException`. | Devuelven `false`. | | Firma vencida (más antigua que la tolerancia) o con fecha futura | Lanzan `EcuafactWebhookException`. | Devuelven `false`. | | Secreto equivocado o ninguno de la lista coincide | Lanzan `EcuafactWebhookException`. | Devuelven `false`. | | Cabecera ausente, vacía o mal formada | Lanzan `EcuafactWebhookException`. | Devuelven `false`, sin lanzar. | | Firma válida, pero el cuerpo no es un evento JSON | Lanzan `EcuafactWebhookException`. | Devuelven `true`: la firma es correcta. | Puedes probar tu receptor sin esperar un evento real. El programa siguiente firma un cuerpo de ejemplo con tu secreto y lo envía a tu endpoint local; si el receptor del ejemplo anterior está funcionando en `http://localhost:5000`, responde 200. Si cambias una letra del cuerpo después de firmarlo, responde 401. ```csharp // Program.cs de un proyecto creado con: dotnet new console // Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run using System.Text; using Ecuafact.Sdk.Webhooks; string secreto = Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET")!; string cuerpo = "{\"eventType\":\"operation.requires_attention\",\"probe\":\"true\"}"; string firma = WebhookSignature.Sign(secreto, DateTimeOffset.UtcNow.ToUnixTimeSeconds(), cuerpo); using HttpClient http = new(); using HttpRequestMessage peticion = new(HttpMethod.Post, "http://localhost:5000/webhooks/ecuafact") { Content = new StringContent(cuerpo, Encoding.UTF8, "application/json") }; peticion.Headers.Add(WebhookSignature.HeaderName, firma); HttpResponseMessage respuesta = await http.SendAsync(peticion); Console.WriteLine((int)respuesta.StatusCode); ``` Responde con un 2xx en cuanto verifiques y registres el evento, y deja el procesamiento pesado para después. Qué hacer ante cada evento está en [Webhooks](/v1/guias/webhooks#que-hacer-ante-cada-evento); por ejemplo, ante `document.rejected` corriges el comprobante y lo emites con una `Idempotency-Key` y una `referenciaExterna` nuevas. Decide siempre con `Estado` y `CodEstado`, no solo con el tipo del evento. Los eventos (`document.authorized`, `document.rejected`, `document.failed` y el aviso `operation.requires_attention`, que también es el de prueba) y su contenido están en [Webhooks](/v1/guias/webhooks); el algoritmo, en [Verificación de firma](/v1/guias/webhooks-firma). ## Errores Todas las excepciones del SDK heredan de `EcuafactSdkException`, y las que vienen de una respuesta de la API heredan además de `EcuafactApiException`. Captura primero las específicas y al final las generales: un `catch (EcuafactApiException)` atrapa todas las respuestas de error de la API, y un `catch (EcuafactSdkException)`, cualquier error del SDK. | Excepción | Hereda de | Cuándo ocurre | Qué hacer | |---|---|---|---| | `EcuafactConfigurationException` | `EcuafactSdkException` | Falta la API Key o la URL; la URL no es HTTPS, contiene credenciales, query string o fragmento, o termina en `/v1`; la API Key tiene espacios o caracteres de control; `MaxAttempts` es menor que 1 o un tiempo es inválido. | Corrige la configuración. No llama a la API. | | `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API (DNS, TLS, conexión rechazada o cortada) tras agotar los intentos. | Reintenta más tarde con la misma `IdempotencyKey`. `EsReintentable` es `true`. | | `EcuafactTimeoutException` | `EcuafactSdkException` | Se agotó `Timeout` en el último intento o `TotalTimeout` de la llamada. | Reintenta con la misma `IdempotencyKey`; si emitías, consulta antes el seguimiento. `EsReintentable` es `true`. | | `EcuafactResponseTooLargeException` | `EcuafactSdkException` | La respuesta superó `MaxResponseBytes` (o `MaxFileResponseBytes` en una descarga). Trae `Limite`, `BytesLeidos` e `IdempotencyKey`. | Sube el tope en las opciones o en esa llamada (`0` lo quita) si esperas una respuesta de ese tamaño. Si emitías, conserva la `IdempotencyKey` y consulta el seguimiento. | | `EcuafactInvalidResponseException` | `EcuafactSdkException` | La API respondió con éxito (2xx), pero el cuerpo no se puede leer como el contrato, por ejemplo porque un proxy lo truncó. Trae `EstadoHttp`, `CorrelationId` e `IdempotencyKey`. | Si estabas emitiendo, la operación pudo haberse creado: repite la emisión con la misma `IdempotencyKey` para recuperar su resultado sin duplicar el comprobante. Si consultabas o validabas, repite la llamada. | | `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida, o cuerpo que no es un evento JSON. | Responde 401 y no proceses el evento. | | `EcuafactAuthException` | `EcuafactApiException` | HTTP 401 o 403, con el `CodEstado` 3009 (`credenciales_invalidas`), 3010 (`ip_no_autorizada`) o 3011 (`acceso_denegado`). | Corrige la API Key, registra la IP o revisa que el contribuyente y el tipo estén habilitados. No reintentes sin cambiar nada. | | `EcuafactValidationException` | `EcuafactApiException` | HTTP 400 o 422, con el `CodEstado` 3002 (`comprobante_invalido`), 3003 (`solicitud_invalida`), 3007 (`version_no_soportada`) o 3012 (`filtros_invalidos`). | Corrige según `Errores`. Un 422 consume 1 documento como intento. | | `EcuafactNotFoundException` | `EcuafactApiException` | HTTP 404, con el `CodEstado` 3013 (`no_encontrado`), o con `CodEstado` en 0 si la ruta no existe y la respuesta no trae cuerpo de error. | Verifica el `idOperacion` o la `claveAcceso`. | | `EcuafactConflictException` | `EcuafactApiException` | HTTP 409, con el `CodEstado` 3004 (`comprobante_duplicado`), 3005 (`conflicto_idempotencia`) o 3014 (`correo_no_disponible`). | Mira el `CodEstado` en la tabla de códigos de abajo. | | `EcuafactRateLimitException` | `EcuafactApiException` | HTTP 429 con un `CodEstado` distinto de 4004, normalmente 5005 (`limite_solicitudes`). | Espera `RetryAfter` y reintenta con la misma `IdempotencyKey`. El SDK ya lo reintenta por defecto, así que la excepción llega cuando se agotan los intentos o si desactivaste `RetryRateLimited`. | | `EcuafactQuotaException` | `EcuafactApiException` | HTTP 429 con el `CodEstado` 4004 (`cupo_agotado`). | Amplía el cupo ([`GET /v1/consumo`](/v1/guias/consumo)). No reintentes, porque esperar no lo repone. | | `EcuafactServerException` | `EcuafactApiException` | HTTP 5xx, con el `CodEstado` 5001 (`error_interno`), 5002 (`servicio_no_disponible`), 5003 (`error_dependencia`) o 5004 (`tiempo_agotado`), tras agotar los intentos si el estado es reintentable. | Reintenta más tarde con la misma `IdempotencyKey`. Un 501 no se reintenta. | | `EcuafactApiException` | `EcuafactSdkException` | Cualquier otro estado de error de la API, por ejemplo 413 con el `CodEstado` 3006 (`cuerpo_excedido`). | Revisa `CodEstado`, `MsgError` y `Errores`. | | `EcuafactSdkException` | `Exception` | Otros errores locales: `Idempotency-Key` inválida, `idOperacion` que no es UUID, falta el contribuyente por defecto, falta un dato obligatorio de una consulta (`apellidos`, `ruc`), cliente con nombre no registrado en inyección de dependencias o respuesta no reconocida. | Corrige la llamada. | Además, el SDK usa excepciones estándar de .NET que no heredan de `EcuafactSdkException`: | Excepción | Cuándo ocurre | Qué hacer | |---|---|---| | `OperationCanceledException` | Cancelaste el `CancellationToken` que pasaste al método. | Nada: es tu cancelación. Si cancelaste una emisión, consulta el seguimiento antes de reenviarla con la misma `Idempotency-Key`. | | `ArgumentNullException`, `ArgumentException`, `ArgumentOutOfRangeException` | Argumento nulo o vacío (comprobante, destinatario, archivo del logo), o `intervalo` o `maximo` inválidos en `EsperarResultadoAsync`. | Corrige el argumento. No se llamó a la API. | Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción conserva la `Idempotency-Key` y el correlativo de la solicitud; repite la emisión con esa misma clave y no se duplica el comprobante. En .NET, esa excepción es `EcuafactInvalidResponseException`, que trae la clave en `IdempotencyKey` y el `X-Correlation-Id` en `CorrelationId`. `EcuafactApiException` y todas sus subclases tienen estas propiedades: | Propiedad | Tipo | Descripción | |---|---|---| | `CodEstado` | `int` | Código numérico del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), por ejemplo 3002 o 3004. Úsalo para decidir en tu código; las constantes están en `CodEstado`. Es 0 si la respuesta no trajo un cuerpo de error de la API. | | `Estado` | `string?` | `estado` de la respuesta de error: `rechazado`, `rechazo_configuracion` o `error`. Su versión tipada es `EstadoOperacion`, que se deduce del primer dígito de `CodEstado` si el campo no llegó. | | `MsgError` | `string?` | Descripción general y fija del código. Muéstrala o regístrala, pero no la uses para decidir. | | `EstadoHttp` | `int` | Estado HTTP de la respuesta. | | `Errores` | `IReadOnlyList` | Detalle específico del error, como la ruta del campo que falla en un 3002. Vacía cuando no hay detalle. | | `CorrelationId` | `string?` | Valor de la cabecera `X-Correlation-Id`. Inclúyelo al pedir soporte. | | `IdempotencyKey` | `string?` | Clave usada en la llamada (solo emisión). Reutilízala al reintentar. | | `RetryAfter` | `TimeSpan?` | Espera indicada por la cabecera `Retry-After`; `null` si no llegó. | | `EsReintentable` | `bool` | `true` si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el `CodEstado` 5005. El 429 con 4004 (cupo agotado) y un 501 no son reintentables. | ```csharp using System.Text.Json; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); FacturaRequest comprobante = JsonSerializer.Deserialize( await File.ReadAllTextAsync("comprobante.json"))!; try { EmisionResultado r = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001"); Console.WriteLine($"{r.Admission.Estado} {r.Admission.IdOperacion}"); } catch (EcuafactValidationException error) { // Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual. foreach (string detalle in error.Errores) Console.WriteLine(detalle); } catch (EcuafactQuotaException) { Console.WriteLine("Cupo agotado: compra un paquete. No reintentes."); } catch (EcuafactRateLimitException error) { Console.WriteLine($"Limite de solicitudes: espera {error.RetryAfter?.TotalSeconds ?? 1} s y reintenta con {error.IdempotencyKey}."); } catch (EcuafactApiException error) when (error.EsReintentable) { Console.WriteLine($"{error.EstadoHttp} codEstado {error.CodEstado}: reintenta mas tarde con {error.IdempotencyKey}."); } catch (EcuafactApiException error) { Console.WriteLine($"{error.EstadoHttp} codEstado {error.CodEstado} {error.MsgError} correlation={error.CorrelationId}"); } catch (EcuafactInvalidResponseException error) { Console.WriteLine($"Respuesta {error.EstadoHttp} ilegible: repite la emision con la MISMA Idempotency-Key ({error.IdempotencyKey}), correlation={error.CorrelationId}."); } catch (EcuafactConnectionException error) { Console.WriteLine($"Sin conexion: reintenta mas tarde con la MISMA Idempotency-Key ({error.IdempotencyKey})."); } catch (EcuafactTimeoutException error) { Console.WriteLine($"Sin respuesta a tiempo: consulta el seguimiento o reintenta con {error.IdempotencyKey}."); } ``` Estos son los códigos que verás con más frecuencia. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado), y cada constante de la clase `CodEstado` lleva el nombre de la columna **Nombre** en PascalCase, por ejemplo `CodEstado.CredencialesInvalidas`. | `CodEstado` | Nombre | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---|---| | 3009 | `credenciales_invalidas` | 401 | API Key ausente o inválida. | Corrige la API Key. No reintentes sin cambiar nada. | | 3010 | `ip_no_autorizada` | 403 | La IP no está permitida o no se pudo identificar. | Registra tu IP en **Cuenta > IP permitidas** o revisa proxies intermedios; si persiste, contacta a soporte con el `CorrelationId`. | | 3011 | `acceso_denegado` | 403 | Contribuyente o tipo de comprobante no habilitado para tu API Key. | Revisa `GetContextoAsync()` (`PuedeEmitir`, `TiposComprobante`). | | 5005 | `limite_solicitudes` | 429 | Superaste el límite de solicitudes por minuto. | Espera `RetryAfter` y reintenta con la misma `Idempotency-Key`, aunque el SDK ya lo hace por defecto; reduce el ritmo de llamadas. | | 3003 | `solicitud_invalida` | 400 | Cabeceras inválidas (por ejemplo, falta `Idempotency-Key`) o JSON mal formado. | Corrige según `Errores`. | | 3002 | `comprobante_invalido` | 422 | Campos del comprobante faltantes o mal formados, campos desconocidos o de otro tipo, o una regla fiscal incumplida (totales, impuestos). | Corrige según `Errores`. Consume 1 documento como intento. | | 3012 | `filtros_invalidos` | 400 | Un filtro de consulta está fuera de rango (fechas o `max`). | Ajusta los filtros a los [límites](/v1/guias/limites). | | 3006 | `cuerpo_excedido` | 413 | El cuerpo supera 2 MiB. | Reduce el comprobante. | | 3004 | `comprobante_duplicado` | 409 | Ya existe un comprobante con ese número recibido, autorizado o rechazado por el SRI. | No reenvíes. Si querías otro comprobante, usa otro `secuencial` u omítelo para que se asigne el siguiente. | | 3005 | `conflicto_idempotencia` | 409 | Misma `Idempotency-Key` (o misma `referenciaExterna`) con otro contenido. | Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. | | 4004 | `cupo_agotado` | 429 | Cupo de documentos agotado. El SDK no lo reintenta. | Revisa `GetConsumoAsync()`; compra un paquete. | | 3013 | `no_encontrado` | 404 | Operación, comprobante o RIDE no encontrado. | Verifica el `idOperacion` o la `claveAcceso`; el RIDE existe solo si está autorizado. | | 5001, 5002, 5003, 5004 | `error_interno`, `servicio_no_disponible`, `error_dependencia`, `tiempo_agotado` | 500, 503, 502, 504 | Error interno, servicio no disponible, o el servicio de validación fiscal falló o no respondió. | El SDK ya reintentó; vuelve a intentar más tarde con la misma `Idempotency-Key`. | ## Idempotencia y reintentos La `Idempotency-Key` evita emitir dos veces el mismo comprobante si una llamada se repite, por ejemplo después de un timeout, de una caída de la red o de un reinicio de tu proceso. - Si no pasas `idempotencyKey`, el SDK genera una (un GUID sin guiones), la usa en todos sus reintentos y te la devuelve en `EmisionResultado.IdempotencyKey` o, si la llamada falla, en la propiedad `IdempotencyKey` de la excepción. - Te recomendamos pasar un valor estable por intención, por ejemplo tu número interno de factura (`FACTURA-2026-0001`), y guárdalo junto al documento. - El SDK valida la clave antes de enviarla con la misma regla de la API: de 1 a 128 caracteres, solo letras, dígitos y `-` `_` `.` `:` `/`. Si no cumple, lanza `EcuafactSdkException` sin llamar a la API. - `GetOperacionAsync` con `string` exige un UUID (con o sin guiones); si no lo es, lanza `EcuafactSdkException` sin llamar a la API. > [!WARNING] > Si reintentas una emisión desde tu aplicación, reutiliza la misma > `Idempotency-Key`. Una clave nueva para el mismo comprobante puede duplicar la > emisión. La tabla resume qué reintenta el SDK por ti y qué queda en tus manos. | Situación | Se reintenta | Detalle | |---|---|---| | HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con `RetryableStatusCodes`. Solo en `GET`, en `POST`/`PUT` con `Idempotency-Key` (la emisión siempre la lleva) y en el cambio de logo. | | HTTP 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí, salvo con `RetryRateLimited = false` | Espera lo que indica `Retry-After` y reintenta. Con `RetryRateLimited = false` lanza `EcuafactRateLimitException` con `RetryAfter`, y decides tú cuándo reintentar. | | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`) | Nunca | Esperar no repone el cupo. Lanza `EcuafactQuotaException`. | | Error de red o timeout de un intento | Sí | Mismas condiciones. Al agotar los intentos lanza `EcuafactConnectionException` o `EcuafactTimeoutException`. | | Descarga de RIDE/XML y cambio de logo | Sí | Se reintentan ante los mismos estados HTTP y errores de red. El cambio de logo no lleva `Idempotency-Key`, pero lo reintentamos porque subir el mismo archivo otra vez deja el perfil igual. | | `ActualizarPerfilAsync` | No | No lleva `Idempotency-Key`; un reintento automático podría repetir el efecto. | | Cualquier otro 4xx | No | Es un error que debes corregir; se lanza la excepción de inmediato. | Entre intentos, el SDK espera `RetryBaseDelay` x intento con `Linear` o `RetryBaseDelay` x 2^(intento-1) con `Exponential`, más un margen aleatorio de 0 a `RetryJitter` x intento. Si la respuesta trae un `Retry-After` mayor y `RespectRetryAfter` es `true`, espera ese tiempo. La espera nunca supera `MaxRetryDelay`. Si configuraste `TotalTimeout` y la siguiente espera no cabe en él, el SDK no reintenta y lanza la última excepción. Con los valores por defecto hay como máximo 3 intentos por llamada, con esperas de unos 200 y 400 ms. El ejemplo siguiente configura reintentos exponenciales, reintenta el 429 por límite de solicitudes y fija un tope de 1 minuto por llamada. ```csharp // Program.cs de un proyecto creado con: dotnet new console using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!, MaxAttempts = 5, RetryBackoff = RetryBackoff.Exponential, // 500 ms, 1 s, 2 s, 4 s RetryBaseDelay = TimeSpan.FromMilliseconds(500), RetryRateLimited = true, MaxRetryDelay = TimeSpan.FromSeconds(30), TotalTimeout = TimeSpan.FromMinutes(1) }); QuotaBucket cupo = await client.GetConsumoAsync(); Console.WriteLine($"Disponibles: {cupo.Disponibles} de {cupo.LimiteDocumentos}"); ``` ## Opciones por llamada Puedes cambiar el tiempo máximo, el tope total, la correlación, los reintentos o la información adicional de una sola llamada sin tocar la configuración del cliente. Todo método que llama a la API acepta, como último parámetro, `RequestOptions? opciones = null`. Incluye `EsperarResultadoAsync` y la vista `Para(...)`. Cada campo con valor reemplaza la configuración del cliente solo en esa llamada; un campo `null` conserva la del cliente. | Campo | Tipo | Valor por defecto | Qué hace | |---|---|---|---| | `Timeout` | `TimeSpan?` | `null` (usa `EcuafactClientOptions.Timeout`) | Tiempo máximo de cada intento de esta llamada. Mayor que cero o `Timeout.InfiniteTimeSpan`. | | `TotalTimeout` | `TimeSpan?` | `null` (usa `EcuafactClientOptions.TotalTimeout`) | Tope de toda la llamada, incluidos reintentos y esperas. Al superarlo lanza `EcuafactTimeoutException`. Mayor que cero. | | `CorrelationId` | `string?` | `null` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres: letras y dígitos ASCII y `.` `_` `-`. | | `Reintentos` | `bool?` | `null` (política del cliente) | `false` hace un solo intento en esta llamada. `true` o `null` conservan la política del cliente: no reactivan los reintentos si `RetryTransientFailures` es `false`. | | `MaxResponseBytes` | `long?` | `null` (usa `EcuafactClientOptions.MaxResponseBytes` o, en una descarga, `MaxFileResponseBytes`) | Tamaño máximo de la respuesta de esta llamada, en bytes. `0` quita el tope solo en esta llamada. No admite negativos. | | `AdditionalInfo` | `string?` | `null` (usa `EcuafactClientOptions.AdditionalInfo`) | Valor de la cabecera `X-Additional-Info` solo en esta llamada; reemplaza el del cliente. Cadena vacía: no se envía la cabecera en esta llamada. Mismas reglas que la opción del cliente. | La cancelación se hace con el `CancellationToken` de cada método: cancela el intento en curso y las esperas entre reintentos. La API devuelve la correlación que enviaste. La encuentras en `EmisionResultado.CorrelationId`, en `EcuafactApiException.CorrelationId` y en `CorrelationId` de `EcuafactConnectionException` y `EcuafactTimeoutException`. Úsala para relacionar tus registros con los nuestros y para pedirnos soporte. ```csharp // Program.cs de un proyecto creado con: dotnet new console // Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); // Un solo intento y correlacion propia para esta consulta. Contexto contexto = await client.GetContextoAsync(opciones: new RequestOptions { Reintentos = false, CorrelationId = "pedido-2026-0457" }); Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}"); // Mas tiempo para una descarga grande, con tope total de 2 minutos. ArchivoComprobante ride = await client.DescargarRideAsync( "0123456789001", "0710202601012345678900110010010000001231234567811", opciones: new RequestOptions { Timeout = TimeSpan.FromSeconds(60), TotalTimeout = TimeSpan.FromMinutes(2) }); await File.WriteAllBytesAsync("ride.pdf", ride.Contenido); ``` Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu emisor. | Error | Por qué pasa | Qué hacer | |---|---|---| | `EcuafactConfigurationException` sin llamar a la API | Un `CorrelationId` vacío, con espacios o de más de 64 caracteres, un tiempo menor o igual a cero, un `MaxResponseBytes` negativo, o un `AdditionalInfo` con caracteres fuera de ASCII imprimible, espacios al inicio o al final o más de 256 caracteres. | Corrige el valor de `RequestOptions`. | | `EcuafactConfigurationException` con `IEcuafactClient` | Pasaste `opciones` a una implementación propia de `IEcuafactClient`. Con la interfaz, las sobrecargas son métodos de extensión que solo funcionan con la instancia que entrega el SDK (`EcuafactClient` o la registrada por inyección de dependencias). | Usa la instancia del SDK o pasa `opciones` nulo. | | La llamada se corta antes del `Timeout` por llamada | Usas tu propio `HttpClient` y su `HttpClient.Timeout` es menor. | Sube `HttpClient.Timeout` o configúralo en `Timeout.InfiniteTimeSpan`. `EcuafactClient.Create` y el registro por inyección de dependencias ya lo dejan infinito. | ## Información adicional Puedes enviar un dato tuyo en cada solicitud, por ejemplo la versión de tu ERP o la sucursal que emite, para que ubiquemos tus llamadas cuando nos pidas soporte. Viaja en la cabecera `X-Additional-Info`; la API la asocia a tu solicitud y no cambia su respuesta. Es la única cabecera personalizada que admite el SDK. Las reglas de la API están en [Límites](/v1/guias/limites#cabeceras). | Dónde | Qué hace | |---|---| | `EcuafactClientOptions.AdditionalInfo` | Se envía en todas las solicitudes del cliente, incluidas las de `EsperarResultadoAsync` y la vista `Para(...)`. | | `RequestOptions.AdditionalInfo` | Reemplaza el valor del cliente solo en esa llamada. `null` conserva el del cliente; cadena vacía no envía la cabecera en esa llamada. | El SDK valida el valor en tu proceso, antes de llamar a la API, con estas reglas: - Solo caracteres ASCII imprimibles (0x20 a 0x7E): sin tildes, `ñ` ni saltos de línea. - Sin espacios al inicio ni al final. - Máximo 256 caracteres (`EcuafactClientOptions.AdditionalInfoMaxLength`). Si no cumple, el SDK lanza `EcuafactConfigurationException` sin llamar a la API. El valor no aparece en `ToString()` de las opciones ni en los mensajes de las excepciones. No pongas en él la API Key ni datos personales. ```csharp // Program.cs de un proyecto creado con: dotnet new console // Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!, AdditionalInfo = "erp=MiERP/4.2; sucursal=001" }); // Todas las solicitudes llevan X-Additional-Info: erp=MiERP/4.2; sucursal=001 Contexto contexto = await client.GetContextoAsync(); // Solo esta llamada lleva otro valor. Contexto otro = await client.GetContextoAsync(opciones: new RequestOptions { AdditionalInfo = "erp=MiERP/4.2; sucursal=002; lote=2026-10-08" }); Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}"); ``` Con inyección de dependencias asígnalo en `AddEcuafactClient` o con la clave `AdditionalInfo` de la sección de configuración. | Error | Por qué pasa | Qué hacer | |---|---|---| | `EcuafactConfigurationException` al crear o resolver el cliente | `AdditionalInfo` tiene tildes, `ñ`, saltos de línea u otro carácter fuera de 0x20 a 0x7E, espacios al inicio o al final, o más de 256 caracteres. | Corrige el valor: quita tildes y espacios de los extremos y acórtalo. | | `EcuafactConfigurationException` en una llamada | El mismo problema en `RequestOptions.AdditionalInfo`. No se llamó a la API. | Corrige el valor de esa llamada. | ## HttpClient propio, proxy y TLS Si tu red sale a internet por un proxy, necesitas un certificado propio o quieres limitar el tiempo de conexión, puedes configurar la conexión de tres formas. | Forma | Cuándo usarla | Quién libera el `HttpClient` | |---|---|---| | `EcuafactClient.Create(options)` con `options.Handler` | Aplicación de consola o servicio sin contenedor de dependencias. | El cliente libera su `HttpClient` al llamar `Dispose`; el handler es tuyo (el SDK no lo libera). | | `AddEcuafactClient` con `options.Handler` | ASP.NET Core o Worker Service. El handler entra como handler principal de `IHttpClientFactory` (ver [Proxy, TLS y handlers propios](#proxy-tls-y-handlers-propios)). | `IHttpClientFactory`. El handler es tuyo: ni el SDK ni la fábrica lo liberan. | | `new EcuafactClient(httpClient, options)` | Ya tienes un `HttpClient` (por ejemplo, de `IHttpClientFactory`). `options.Handler` no se usa. | Tú. `Dispose` del cliente no lo libera. | Con un `HttpClient` propio, el SDK aplica igual en cada solicitud la API Key, `Timeout` (por intento) y `UserAgent`, y usa la `BaseAddress` de las opciones o, si es `null`, la del `HttpClient`. Su `HttpClient.Timeout` es también un tope: si es menor que `Timeout`, la llamada se corta antes y lanza `EcuafactTimeoutException`. Déjalo en `Timeout.InfiniteTimeSpan` para que mande el `Timeout` del SDK. El transporte predeterminado desactiva las redirecciones automáticas y las cookies. Si proporcionas un handler o un `HttpClient`, configura también `AllowAutoRedirect = false` y `UseCookies = false` en su transporte; el SDK no puede cambiar las opciones de un cliente que ya construiste. Usa directamente la URL HTTPS final del servicio. Este ejemplo usa `Handler` para configurar un proxy y el tiempo de conexión, y además ajusta los reintentos. `SocketsHttpHandler.ConnectTimeout` existe en .NET 5 o superior; en .NET Framework usa `HttpClientHandler` con su propiedad `Proxy`. ```csharp // Program.cs de un proyecto creado con: dotnet new console using System.Net; using System.Net.Http; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using SocketsHttpHandler handler = new() { AllowAutoRedirect = false, UseCookies = false, Proxy = new WebProxy("http://proxy.miempresa.local:8080"), ConnectTimeout = TimeSpan.FromSeconds(10) }; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!, RetryBackoff = RetryBackoff.Exponential, RetryBaseDelay = TimeSpan.FromMilliseconds(500), RetryRateLimited = true, TotalTimeout = TimeSpan.FromMinutes(1), Handler = handler }); Console.WriteLine(client.Options); // la API Key aparece como *** Contexto contexto = await client.GetContextoAsync(); Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}"); ``` Y este otro usa tu propio `HttpClient`: ```csharp // Program.cs de un proyecto creado con: dotnet new console using System.Net.Http; using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using HttpClientHandler handler = new() { AllowAutoRedirect = false, UseCookies = false }; using HttpClient http = new(handler) { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), Timeout = Timeout.InfiniteTimeSpan // el SDK aplica su Timeout por intento }; EcuafactClient client = new(http, new EcuafactClientOptions { ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); Contexto contexto = await client.GetContextoAsync(); Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}"); ``` En ASP.NET Core usa [Proxy, TLS y handlers propios](#proxy-tls-y-handlers-propios) con `IHttpClientFactory`. ## Inyección de dependencias En ASP.NET Core o en un Worker Service, instala también el paquete `Ecuafact.Sdk.Core`. ```bash dotnet add package Ecuafact.Sdk.Core ``` Registra el cliente en `Program.cs`. La configuración de .NET lee las variables de entorno, así que `ECUAFACT_API_KEY` está disponible en `builder.Configuration`: ```csharp using Ecuafact.Sdk; using Ecuafact.Sdk.Core; WebApplicationBuilder builder = WebApplication.CreateBuilder(args); builder.Services.AddEcuafactClient(o => { o.BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"); o.ApiKey = builder.Configuration["ECUAFACT_API_KEY"]!; // o.Identificacion = "0123456789001"; // solo si usas un unico contribuyente }); WebApplication app = builder.Build(); app.MapGet("/contexto", async (IEcuafactClient client) => { var contexto = await client.GetContextoAsync(); return Results.Ok(contexto.Contribuyentes); }); app.Run(); ``` `AddEcuafactClient` registra un `HttpClient` administrado por `IHttpClientFactory` y expone `IEcuafactClient` como transient, de modo que cada resolución crea un cliente liviano sobre el `HttpClient` de la fábrica. Si no asignas `ApiKey` ni `BaseAddress`, se leen `ECUAFACT_API_KEY` y `ECUAFACT_BASE_URL`. Las opciones se validan al resolver el cliente, no al registrarlo: una configuración inválida lanza `EcuafactConfigurationException` la primera vez que se inyecta. Inyéctalo en tus servicios: ```csharp using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; public sealed class Facturacion(IEcuafactClient client) { public async Task EmitirAsync(FacturaRequest comprobante, string numeroInterno, CancellationToken ct) { EmisionResultado r = await client.EmitirAsync("0123456789001", comprobante, numeroInterno, ct); return r.Admission.IdOperacion.ToString(); } } ``` ### Desde configuración También puedes registrar el cliente desde una sección de `appsettings.json`: ```json { "Ecuafact": { "BaseAddress": "https://api-sandbox.mynexusapi.com/", "Identificacion": "0123456789001", "MaxAttempts": 3, "RetryRateLimited": true, "RetryBackoff": "Exponential", "TotalTimeout": "00:01:00", "RetryableStatusCodes": [ 408, 425, 500, 502, 503, 504 ] } } ``` ```csharp using Ecuafact.Sdk.Core; WebApplicationBuilder builder = WebApplication.CreateBuilder(args); builder.Services.AddEcuafactClient(builder.Configuration.GetSection("Ecuafact")); WebApplication app = builder.Build(); app.Run(); ``` La sección admite estas claves: `BaseAddress` (o `BaseUrl`), `ApiKey`, `Identificacion`, `Timeout`, `UserAgent`, `RetryTransientFailures`, `MaxAttempts`, `RespectRetryAfter`, `MaxRetryDelay`, `RetryRateLimited`, `RetryableStatusCodes`, `RetryBaseDelay`, `RetryBackoff`, `RetryJitter`, `TotalTimeout`, `MaxResponseBytes`, `MaxFileResponseBytes` (en bytes; `0` quita el tope) y `AdditionalInfo`. Los tiempos aceptan `hh:mm:ss` o segundos. > [!WARNING] > No guardes la API Key en `appsettings.json` ni en el repositorio. Usa > `ECUAFACT_API_KEY`, secretos de usuario o un almacén de secretos. ### Proxy, TLS y handlers propios `AddEcuafactHttpClient` registra el cliente y devuelve el `IHttpClientBuilder` de su `HttpClient`, para configurar el handler principal (proxy, certificados, tiempo de conexión) o agregar tus propios handlers: ```csharp using System.Net; using System.Net.Http; using Ecuafact.Sdk.Core; WebApplicationBuilder builder = WebApplication.CreateBuilder(args); builder.Services.AddEcuafactHttpClient(o => { o.BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"); o.ApiKey = builder.Configuration["ECUAFACT_API_KEY"]!; }) .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { AllowAutoRedirect = false, UseCookies = false, Proxy = new WebProxy("http://proxy.miempresa.local:8080"), ConnectTimeout = TimeSpan.FromSeconds(10) }); WebApplication app = builder.Build(); app.Run(); ``` Para un cliente ya registrado con `AddEcuafactClient`, obtén el mismo builder con `builder.Services.ConfigureEcuafactHttpClient("nombre")` (sin nombre, el cliente por defecto). También puedes asignar `options.Handler` en `AddEcuafactClient`: entra como handler principal del `HttpClient` de la fábrica, así que todas las resoluciones comparten sus conexiones y `AddHttpMessageHandler` sigue funcionando. La fábrica no libera tu handler al rotar. Crea la instancia fuera de la lambda de configuración, porque la lambda se ejecuta en cada resolución y en cada rotación de la fábrica: ```csharp using System.Net; using System.Net.Http; using Ecuafact.Sdk.Core; WebApplicationBuilder builder = WebApplication.CreateBuilder(args); SocketsHttpHandler proxy = new() { AllowAutoRedirect = false, UseCookies = false, Proxy = new WebProxy("http://proxy.miempresa.local:8080"), ConnectTimeout = TimeSpan.FromSeconds(10) }; builder.Services.AddEcuafactClient(o => { o.BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"); o.ApiKey = builder.Configuration["ECUAFACT_API_KEY"]!; o.Handler = proxy; }); WebApplication app = builder.Build(); app.Run(); ``` Si además llamas a `ConfigurePrimaryHttpMessageHandler` sobre el builder que devuelve `AddEcuafactHttpClient` o `ConfigureEcuafactHttpClient`, ese handler tiene prioridad sobre `options.Handler`. ### Varias API Key Si usas varias API Key, por ejemplo para dos integraciones distintas, registra clientes con nombre y obtenlos con `IEcuafactClientProvider`. ```csharp using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using Ecuafact.Sdk.Core; WebApplicationBuilder builder = WebApplication.CreateBuilder(args); builder.Services.AddEcuafactClient("integracionA", o => { o.BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"); o.ApiKey = builder.Configuration["ECUAFACT_API_KEY_A"]!; }); builder.Services.AddEcuafactClient("integracionB", builder.Configuration.GetSection("EcuafactB")); builder.Services.AddTransient(); WebApplication app = builder.Build(); app.MapGet("/contexto-a", async (Multi multi) => Results.Ok(await multi.ContextoAAsync())); app.Run(); public sealed class Multi(IEcuafactClientProvider provider) { public Task ContextoAAsync() => provider.GetClient("integracionA").GetContextoAsync(); } ``` `IEcuafactClient` solo se inyecta directamente para el cliente sin nombre; los clientes con nombre se obtienen con `provider.GetClient("nombre")`. Un nombre no registrado lanza `EcuafactSdkException`. ## Constructores de comprobantes Puedes armar la [Estructura del comprobante](/v1/guias/emision) con métodos en lugar de escribir el JSON. Los constructores solo ensamblan el cuerpo con los valores que les entregas: no calculan subtotales, impuestos, totales ni redondeos, no completan valores por defecto y no validan reglas de negocio. Esas reglas viven solo en la API, que calcula y valida al emitir (o en [`ValidarAsync`](#validar-sin-emitir)). Los constructores son opcionales y están en `Ecuafact.Sdk.Builders`. Producen el mismo request de su tipo (`FacturaRequest`, `NotaCreditoRequest`...) que armas a mano. ```csharp // Program.cs de un proyecto creado con: dotnet new console // Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run using Ecuafact.Sdk; using Ecuafact.Sdk.Builders; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); // Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor. // Los importes los entregas tu; el SDK no los calcula. Impuesto iva = new() { Codigo = "2", CodigoPorcentaje = "4", Tarifa = 15m, BaseImponible = 10.00m, Valor = 1.50m }; FacturaRequest comprobante = ComprobanteBuilder.Factura("0123456789001", "001", "001") .Referencias("MiERP", "FACTURA-2026-0002") .FechaEmision(DateTime.UtcNow.AddHours(-5).Date) // fecha de hoy en Ecuador .Comprador("07", "9999999999999", "CONSUMIDOR FINAL") .Linea("SERV-001", "Servicio de prueba", 1m, 10.00m, 0m, 10.00m, iva) .Configurar(r => { r.Info!.TotalSinImpuestos = 10.00m; r.Info.TotalDescuento = 0m; r.Info.TotalConImpuestos = new List { iva }; r.Info.ImporteTotal = 11.50m; r.Info.Propina = 0m; r.Info.Moneda = "DOLAR"; }) .Pago("01", 11.50m) .Construir(); EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0002", opciones: new RequestOptions { CorrelationId = "pedido-2026-0458" }); Console.WriteLine($"{resultado.Admission.Estado} {resultado.Admission.IdOperacion} {resultado.CorrelationId}"); ``` Deberías ver `recibido pedido-2026-0458`. Si falta o no cuadra algún importe, la API responde 422 (`codEstado` 3002) con `errores`. Si ejecutas el programa otro día con la misma `Idempotency-Key`, la API responde 409 con el `codEstado` 3005; en ese caso usa una `Idempotency-Key` y una `referenciaExterna` nuevas. | Tipo | Entrada | Métodos propios | |---|---|---| | Factura (`01`) | `ComprobanteBuilder.Factura(ruc, estab, ptoEmi)` | `Comprador(tipoIdentificacion, identificacion, razonSocial, direccion?)`, `Linea`, `DetalleAdicional`, `Propina`, `Moneda`, `Pago(formaPago, total?, plazo?, unidadTiempo?)` | | Liquidación de compra (`03`) | `ComprobanteBuilder.LiquidacionCompra(ruc, estab, ptoEmi)` | `Proveedor(tipoIdentificacion, identificacion, razonSocial, direccion?)`, `Linea`, `DetalleAdicional`, `Moneda`, `Pago` | | Nota de crédito (`04`) | `ComprobanteBuilder.NotaCredito(ruc, estab, ptoEmi)` | `Comprador`, `DocumentoModificado(codDocModificado, numero, fechaEmision, totalDocumentoSustento?)`, `Motivo(motivo)`, `Linea` (el código va en `codigoInterno`), `DetalleAdicional`, `Moneda` | | Nota de débito (`05`) | `ComprobanteBuilder.NotaDebito(ruc, estab, ptoEmi)` | `Comprador`, `DocumentoModificado(codDocModificado, numero, fechaEmision)`, `Impuestos(params Impuesto[])`, `Motivo(razon, valor)`, `Moneda`, `Pago` | | Guía de remisión (`06`) | `ComprobanteBuilder.GuiaRemision(ruc, estab, ptoEmi)` | `DirPartida`, `Transportista(tipoIdentificacion, identificacion, razonSocial, placa)`, `Traslado(inicio, fin)`, `Destinatario(identificacion, razonSocial, direccion, motivoTraslado, codEstabDestino?, ruta?)`, `Detalle(codigoInterno, descripcion, cantidad)` | | Retención (`07`) | `ComprobanteBuilder.Retencion(ruc, estab, ptoEmi)` | `SujetoRetenido`, `PeriodoFiscal(mes, anio)`, `ParteRelacionada`, `DocSustento(...)`, `ImpuestoDocSustento(...)`, `Retener(codigo, codigoRetencion, baseImponible, porcentajeRetener, valorRetenido?)`, `Pago` | Todos los constructores tienen además `Referencias(origen, externa)`, `Secuencial`, `DirEstablecimiento`, `InfoAdicional(nombre, valor)`, `Configurar(Action)`, con el request del tipo (asigna cualquier campo tal cual) y `Construir()`. `FechaEmision(DateTime)` existe en todos salvo la guía de remisión, que usa `Traslado(inicio, fin)`; factura, liquidación de compra y nota de crédito aceptan también el texto `dd/MM/yyyy`. `DetalleAdicional` se aplica a la última línea agregada: llámalo después de `Linea`, o lanza `InvalidOperationException`. **Lo que asignas se envía tal cual.** Todo valor (subtotal de línea, impuestos, bases, totales, propina, moneda, pagos) viaja sin cambios y lo que no asignas queda sin enviar. Las tarifas de IVA y los códigos válidos están en el [catálogo](/v1/guias/catalogos); el SDK no los conoce. Para comprobar el cuerpo antes de emitir usa [`ValidarAsync`](#validar-sin-emitir) o activa [`ValidarAntesDeEmitir`](#validar-antes-de-cada-emision). ## Importes exactos Todos los importes, cantidades, precios y tarifas del SDK .NET son `decimal` (`decimal?` en la solicitud). Un `decimal` guarda `0.30` como `0.30`, sin el error de redondeo de `double`, y se envía como número JSON con punto decimal. Calcula con `decimal` (sufijo `m` en los literales) y redondea a 2 decimales antes de asignar: ```csharp using System.Text.Json; using Ecuafact.Sdk.Contracts; FacturaRequest comprobante = JsonSerializer.Deserialize( await File.ReadAllTextAsync("comprobante.json"))!; decimal baseImponible = 10.00m; decimal iva = Math.Round(baseImponible * 0.15m, 2, MidpointRounding.AwayFromZero); // 1.50 comprobante.Info!.TotalSinImpuestos = baseImponible; comprobante.Info.ImporteTotal = baseImponible + iva; // 11.50 Console.WriteLine(comprobante.Info.ImporteTotal); // 11.50 ``` En las respuestas, `Comprobante.Total` y `CatalogoItem.Valor` también son `decimal`. Las reglas de cálculo de cada comprobante están en [Factura](/v1/guias/emision-01). ## Varios contribuyentes Si tu API Key maneja varios contribuyentes, no fijes `Identificacion` en las opciones. Pasa la identificación en cada llamada o crea una vista por contribuyente con `Para`. La vista repite la identificación por ti en cada método: ```csharp using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); IEcuafactContribuyente matriz = client.Para("0123456789001"); PerfilEmisor perfil = await matriz.GetPerfilAsync(); Console.WriteLine($"{perfil.RazonSocial} ({perfil.Identificacion})"); ``` La vista `IEcuafactContribuyente` tiene estos métodos: | Método | Equivale a | |---|---| | `EmitirAsync(comprobante, idempotencyKey?)` | `client.EmitirAsync(identificacion, comprobante, idempotencyKey)` | | `ValidarAsync(comprobante)` | `client.ValidarAsync(identificacion, comprobante)` | | `DescargarRideAsync(claveAcceso)` | `client.DescargarRideAsync(identificacion, claveAcceso)` | | `DescargarXmlAsync(claveAcceso)` | `client.DescargarXmlAsync(identificacion, claveAcceso)` | | `GetPerfilAsync()` | `client.GetPerfilAsync(identificacion)` | | `ActualizarPerfilAsync(cambios)` | `client.ActualizarPerfilAsync(identificacion, cambios)` | | `ActualizarLogoAsync(contenido, contentType, nombreArchivo)` | `client.ActualizarLogoAsync(identificacion, ...)` | | `EsperarResultadoAsync(idOperacion, intervalo?, maximo?)` | `client.EsperarResultadoAsync(idOperacion, ...)` | | `GetConsumoAsync()` | `client.GetConsumoAsync()` (el cupo es de la API Key, no del contribuyente) | Puedes usar varias vistas en paralelo con el mismo cliente. ## Logo del perfil Con `ActualizarLogoAsync` puedes subir el logo que aparece en el RIDE de tu contribuyente sin armar la petición `multipart/form-data`; recibes el `PerfilEmisor` actualizado. Acepta PNG o JPEG de hasta 512 KB. Si la subida falla por un corte de red o un estado HTTP transitorio, nuestro SDK la reintenta por ti. ```csharp using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); byte[] logo = await File.ReadAllBytesAsync("logo.png"); PerfilEmisor perfil = await client.ActualizarLogoAsync("0123456789001", logo, "image/png", "logo.png"); Console.WriteLine($"Logo actualizado para {perfil.RazonSocial}: {perfil.Logo}"); ``` Las reglas del archivo y los errores posibles están en [Perfil del emisor](/v1/guias/perfil-emisor). ## Consultas SRI Con estos métodos puedes consultar el catastro del SRI. No consumen cupo y usan la misma API Key que el resto del cliente. ```csharp using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); ValidacionIdentificacion validacion = await client.ValidarIdentificacionAsync("0123456789001"); ContribuyenteConsulta contribuyente = await client.ConsultarContribuyenteAsync("0123456789001"); IReadOnlyList encontrados = await client.BuscarContribuyentesAsync("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10); EstablecimientosContribuyente establecimientos = await client.ListarEstablecimientosAsync("0123456789001", "SoloActivos"); Console.WriteLine($"valido={validacion.Valido}"); ``` Los parámetros y las respuestas de cada consulta están en [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). ## Estado del servicio y catálogos `ObtenerEstadoServicioAsync` devuelve el estado público del servicio: el estado global, el estado de cada componente, la disponibilidad de los últimos 90 días y los incidentes. Es la misma información de [Estado del servicio](/v1/guias/estado-del-servicio) (`GET /estado`); no envía la API Key y no consume cupo. `ListarCatalogosAsync` devuelve la clave y la descripción de cada catálogo del SRI, y `ObtenerCatalogoAsync` devuelve las filas de uno de ellos a partir de esa clave. Estas dos consultas usan tu API Key y tampoco consumen cupo. Los catálogos cambian pocas veces al año, así que puedes guardar la respuesta en caché por una hora. ```csharp using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); EstadoPublico estado = await client.ObtenerEstadoServicioAsync(); Console.WriteLine($"{estado.Estado}, disponibilidad 90 días: {estado.Disponibilidad90Dias}"); foreach (IncidentePublico incidente in estado.Incidentes) { Console.WriteLine($"{incidente.Inicio:u} {incidente.Impacto}: {incidente.Titulo}"); } Catalogos indice = await client.ListarCatalogosAsync(); CatalogoDetalle tarifas = await client.ObtenerCatalogoAsync("tarifas-iva"); foreach (CatalogoItem fila in tarifas.Items) { Console.WriteLine($"{fila.Codigo} {fila.Descripcion} {fila.Valor}"); } ``` `ObtenerEstadoServicioAsync` devuelve un `EstadoPublico`: | Propiedad | Tipo | Descripción | |---|---|---| | `Estado` | `string` | Estado global: `operativo`, `degradado`, `caido` o `sin_datos`. | | `MedidoEn` | `DateTime?` | Momento de la última medición. Es `null` mientras no hay mediciones. | | `Componentes` | `List` | Componentes monitoreados, cada uno con `Nombre` y `Estado` (mismos valores que el estado global). | | `Disponibilidad90Dias` | `decimal?` | Porcentaje de minutos sin caída en los últimos 90 días. Es `null` si aún no hay muestras. | | `Incidentes` | `List` | Incidentes de los últimos 90 días y los abiertos, del más reciente al más antiguo. Lista vacía si no hubo ninguno. | | `Incidentes[].Inicio` | `DateTime` | Inicio del incidente. | | `Incidentes[].Fin` | `DateTime?` | Fin del incidente. Es `null` mientras sigue abierto. | | `Incidentes[].Impacto` | `string` | `degradado` o `caido`. | | `Incidentes[].Titulo` | `string` | Título breve. | | `Incidentes[].Detalle` | `string?` | Qué significó para las integraciones. Es `null` si no hay detalle. | `ListarCatalogosAsync` devuelve un `Catalogos`, y `ObtenerCatalogoAsync`, un `CatalogoDetalle`: | Propiedad | Tipo | Descripción | |---|---|---| | `Catalogos.Items` | `List` | Catálogos disponibles, cada uno con `Nombre` (la clave que recibe `ObtenerCatalogoAsync`) y `Descripcion`. | | `CatalogoDetalle.Nombre` | `string` | Clave del catálogo. | | `CatalogoDetalle.Descripcion` | `string` | Descripción breve. | | `CatalogoDetalle.Fuente` | `string` | Tabla o anexo de la ficha técnica del SRI de donde proviene. | | `CatalogoDetalle.Items` | `List` | Filas del catálogo. | | `CatalogoItem.Codigo` | `string` | Código tal como va en el comprobante. | | `CatalogoItem.Descripcion` | `string` | Descripción del código. | | `CatalogoItem.Valor` | `decimal?` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. Es `null` si el catálogo no lo tiene. | | `CatalogoItem.VigenteDesde` | `string?` | Primer día de vigencia, en formato `yyyy-MM-dd`. Es `null` si no está acotada por el inicio. | | `CatalogoItem.VigenteHasta` | `string?` | Último día de vigencia, en formato `yyyy-MM-dd`. Es `null` si sigue vigente. | | `CatalogoItem.Atributos` | `Dictionary?` | Atributos propios del catálogo. Es `null` si no hay. | Una clave de catálogo que no existe lanza `EcuafactNotFoundException`. El significado de cada catálogo y de sus claves está en [Catálogos](/v1/guias/catalogos#consultar-los-catalogos-por-api). ## Listado de comprobantes emitidos `ListarOperacionesAsync` consulta los comprobantes emitidos de un contribuyente. Acepta `desde` y `hasta` en formato `yyyy-MM-dd`, `tipoDocumento`, `buscar`, `pagina` desde 1 y `tamanoPagina` entre 1 y 100. Devuelve `PaginaComprobantes` con `Comprobantes`, `Pagina`, `TamanoPagina` y `HayMas`. Incrementa `pagina` mientras `HayMas` sea `true` para recorrer el resultado. ```csharp // Archivo: Program.cs using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"), ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")! }); PaginaComprobantes resultado = await client.ListarOperacionesAsync( "0123456789001", desde: "2026-11-01", hasta: "2026-11-12", tamanoPagina: 20); Console.WriteLine($"Recibidos: {resultado.Comprobantes.Count}; hay mas: {resultado.HayMas}"); ``` Todos los métodos del SDK admiten `CancellationToken ct` y `RequestOptions? opciones` al final. ## Siguientes pasos - [Factura](/v1/guias/emision-01): revisa todos los campos y las reglas de cálculo para construir tus comprobantes. - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta qué significa cada `estado` y cada `codEstado`. - [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI sin consultar en bucle. - [Visión general de los SDK](/v1/guias/sdk): compara los cinco SDK y decide entre SDK o HTTP directo. --- # SDK Node.js Biblioteca oficial para emitir comprobantes desde Node.js 18 o superior, con tipos de TypeScript, seguir su autorización y verificar webhooks. Si desarrollas en JavaScript o TypeScript, puedes integrarte con nuestros servicios de facturación usando nuestro SDK para Node.js. En lugar de armar cada petición con `fetch`, llamas a métodos como `emitirFactura` o `descargarRide`, que devuelven promesas con objetos tipados. Puedes reintentar sin miedo a duplicar comprobantes, porque el SDK reutiliza la `Idempotency-Key` en sus reintentos. Además, envía tu API Key en cada llamada, te indica si llegaste al límite de solicitudes o si se agotó tu cupo, y verifica la firma de los webhooks que te enviamos. Esta guía sigue el orden de una integración. Primero instalas el paquete, configuras el cliente, emites tu primera factura y haces el seguimiento hasta el resultado del SRI; después recibes webhooks y manejas los errores, y al final ajustas los reintentos, las opciones por llamada y la conexión, y armas comprobantes con los constructores. La [referencia de métodos](#metodos) está al final. Si todavía no decides entre el SDK y la API por HTTP directo, compáralos en [SDKs](/v1/guias/sdk). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan > `https://api-sandbox.mynexusapi.com`; cambia a `https://api.mynexusapi.com` > solo cuando emitas comprobantes reales. ## 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: ```text Instala el SDK Node.js de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. 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/sdk-node.md antes de escribir código; no inventes campos. Reutiliza el lenguaje, el gestor de paquetes y la estructura del proyecto; si no hay proyecto, crea uno mínimo. Instala con npm install @ecuafact/sdk. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Requiere Node.js 18 o superior con módulos ES. 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 programa e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer. ``` ## Paquete | Dato | Valor | |---|---| | Paquete npm | [`@ecuafact/sdk`](https://www.npmjs.com/package/@ecuafact/sdk) | | Versión | `1.0.1` | | Node.js | 18 o superior, porque usa el `fetch` nativo. | | Formato | Módulo ES (`import`). Incluye tipos TypeScript (`.d.ts`). | | Dependencias | No tiene dependencias en tiempo de ejecución. | El paquete se distribuye solo como módulo ES. En un proyecto CommonJS, cárgalo con `const { EcuafactClient } = await import("@ecuafact/sdk");` dentro de una función `async`. ## Requisitos - [ ] Node.js 18 o superior, que compruebas con `node --version`. - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, crea tu sandbox como se explica en [Sandbox de pruebas](/v1/guias/sandbox). - [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier IP. En producción, la IP desde la que ejecutas el código debe estar en **Cuenta > IP permitidas**; si no lo está, la API responde 403 con el `codEstado` 3010 (`ip_no_autorizada`). ## Instalación ```bash mkdir ecuafact-prueba && cd ecuafact-prueba npm init -y npm install @ecuafact/sdk ``` Para verificar la instalación, ejecuta `npm ls @ecuafact/sdk`, que debe mostrar `@ecuafact/sdk@1.0.1`. ## Configuración Crea el cliente **una vez** y reutilízalo, porque sirve para todos los [contribuyentes](/v1/guias/glosario) de tu API Key. ```javascript // Node.js 18 o superior. Guarda como cliente.mjs y ejecuta: node cliente.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY, identificacion: "0123456789001" // opcional: contribuyente por defecto }); console.log(client.options); // la API Key aparece como [oculta] ``` Si no pasas `apiKey`, el SDK lee la variable de entorno `ECUAFACT_API_KEY`, y si no pasas `baseAddress`, lee `ECUAFACT_BASE_URL`. Con las dos variables definidas basta `new EcuafactClient()`. Eliges el ambiente con la URL que configuras, porque el SDK no tiene una opción aparte para eso. Usa `https://api-sandbox.mynexusapi.com/` para pruebas y `https://api.mynexusapi.com/` para producción, **sin** `/v1`, ya que el SDK agrega la versión a cada ruta. | Opción | Tipo | Valor por defecto | Descripción | |---|---|---|---| | `baseAddress` | `string` | `ECUAFACT_BASE_URL` | URL absoluta HTTPS, sin `/v1`, sin usuario, consulta ni fragmento. | | `apiKey` | `string` | `ECUAFACT_API_KEY` | Tu API Key; viaja en la cabecera `X-Api-Key`. No puede tener espacios al inicio o al final ni caracteres de control. No aparece en `console.log`, `util.inspect` ni `JSON.stringify`; si la necesitas, léela con `client.options.apiKey`. | | `identificacion` | `string` | - | Contribuyente por defecto para los métodos `emitir` y `validar` sin `En`. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). | | `timeoutMs` | `number` | `30000` | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta, en milisegundos. Mayor que 0. | | `maxResponseBytes` | `number \| null` | 32 MiB (`33554432`); 100 MiB (`104857600`) en las descargas de RIDE y XML | Tope en bytes del cuerpo de una respuesta. Un número lo aplica a todas las llamadas, incluidas las descargas; `0` o `null` lo desactiva. Al superarlo lanza `EcuafactResponseTooLargeException` con `limite` y `bytesLeidos`. | | `additionalInfo` | `string` | - | Texto que se envía en la cabecera `X-Additional-Info` de cada solicitud, por ejemplo el nombre y la versión de tu ERP; no se guarda con el comprobante. Si la omites o la dejas vacía, la cabecera no se envía. Sus reglas están en [Información adicional](#informacion-adicional). | | `userAgent` | `string` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. | | `validarAntesDeEmitir` | `boolean` | `false` | Si es `true`, `emitir` y `emitirEn` llaman primero a `/validar` y no envían la emisión cuando la API responde `valido: false` (ver [Validar antes de emitir](#validar-antes-de-emitir-opcional)). Cada emisión hace dos peticiones, así que déjalo en `false` en producción salvo que lo necesites. | | `retryTransientFailures` | `boolean` | `true` | Reintenta fallos transitorios (ver [Idempotencia y reintentos](#idempotencia-y-reintentos)). `false` desactiva todo reintento. | | `maxAttempts` | `number` | `3` | Intentos por solicitud, incluido el primero. Entero 1 o mayor. | | `respectRetryAfter` | `boolean` | `true` | Espera lo que indique la cabecera `Retry-After` antes de reintentar. | | `maxRetryDelayMs` | `number` | `60000` | Espera máxima entre reintentos, en milisegundos. Con `0` no hay tope. | | `retryRateLimited` | `boolean` | `true` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`), respetando `Retry-After` y `maxRetryDelayMs`. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. | | `retryableStatusCodes` | `number[]` | `[408, 425, 500, 502, 503, 504]` | Estados HTTP que se reintentan (enteros de 100 a 599). El 429 no va aquí: lo controla `retryRateLimited`. Los valores por defecto están en la constante exportada `DEFAULT_RETRYABLE_STATUS_CODES`. | | `retryBaseDelayMs` | `number` | 200 | Espera base entre reintentos, en milisegundos. | | `retryBackoff` | `"linear" \| "exponential"` | `"linear"` | `linear`: base x intento (200, 400, 600 ms). `exponential`: base x 2^(intento-1) (200, 400, 800 ms). | | `retryJitterMs` | `number` | `50` | Variación aleatoria que se suma a cada espera, en milisegundos: hasta `retryJitterMs` x intento en `linear` y hasta `retryJitterMs` en `exponential`. | | `totalTimeoutMs` | `number` | `0` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas, en milisegundos. Al superarlo lanza `EcuafactTimeoutException`. | | `fetch` | `typeof fetch` | `globalThis.fetch` | Tu propia implementación de `fetch`, por ejemplo la de `undici` o un doble de pruebas. | | `dispatcher` | `unknown` | - | `dispatcher` de `undici` que se pasa a cada `fetch` para usar un proxy (`ProxyAgent`), una CA propia o un tiempo de conexión (`Agent`). El detalle está en [Proxy, TLS y tiempo de conexión](#proxy-tls-y-tiempo-de-conexion). | ```js new EcuafactClient({ maxResponseBytes: 64 * 1024 * 1024 }); // 64 MiB; null desactiva el tope ``` Las opciones se validan al crear el cliente. El constructor lanza `EcuafactConfigurationException`, antes de hacer cualquier llamada, en cualquiera de estos casos: - Falta la API Key o la URL. - La URL no es HTTPS, tiene usuario, consulta o fragmento, o termina en `/v1`. - La API Key tiene espacios o caracteres de control. - `additionalInfo` no cumple su formato. - `maxAttempts` no es un entero 1 o mayor. - `timeoutMs` no es mayor que 0, u otro tiempo es negativo. - `maxResponseBytes` no es un entero mayor que 0, `0` ni `null`. - `validarAntesDeEmitir` no es `true` ni `false`. - `retryBackoff` tiene un valor distinto de los admitidos. - `retryableStatusCodes` trae un código fuera del rango de 100 a 599. El mensaje de la excepción nunca incluye la API Key. ## Quickstart: de la API Key al RIDE Este script hace el flujo completo en el ambiente de pruebas: lee tu [contexto](/v1/guias/consulta-contexto), emite una factura, espera el resultado del SRI con el [seguimiento](/v1/guias/consulta-operacion) y descarga el [RIDE](/v1/guias/glosario), el PDF del comprobante. ### Paso 1. Guarda el comprobante Guarda este JSON como `comprobante.json` en la carpeta del proyecto. Es una factura a consumidor final, con el tipo de identificación `07` y la identificación `9999999999999`, que solo se admite en facturas de hasta 50.00. Factura 10.00 más el IVA del 15 %, que son 1.50, por un total de 11.50. No lleva `secuencial`, porque te asignamos el siguiente [secuencial](/v1/guias/glosario) de la serie `estab`-`ptoEmi`. El script reemplaza `ruc` por el de tu contexto y `fechaEmision` por la fecha de hoy. ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "07", "identificacionComprador": "9999999999999", "razonSocialComprador": "CONSUMIDOR FINAL", "totalSinImpuestos": 10.00, "totalDescuento": 0.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "baseImponible": 10.00, "valor": 1.50 } ], "propina": 0.00, "importeTotal": 11.50, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 11.50 } ] }, "detalles": [ { "codigoPrincipal": "SERV-001", "descripcion": "Servicio de prueba", "cantidad": 1, "precioUnitario": 10.00, "descuento": 0.00, "precioTotalSinImpuesto": 10.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 10.00, "valor": 1.50 } ] } ] } ``` El cuerpo no lleva el tipo de comprobante: lo da el método que eliges (`emitirFactura` para una factura) y la ruta que ese método usa, como se explica en [Tipo de comprobante y ruta](#tipo-de-comprobante-y-ruta). `estab` y `ptoEmi` deben ser un [establecimiento](/v1/guias/glosario) y un [punto de emisión](/v1/guias/glosario) de tu emisor; el sandbox crea el establecimiento `001` con el punto de emisión `001`. Cada campo está explicado en [Factura](/v1/guias/emision-01). ### Paso 2. Escribe el script Guarda el código siguiente como `quickstart.mjs`. El paso 4 usa `esperarResultado`, un método **opcional** que consulta la operación cada 5 segundos hasta tener un resultado final o hasta 2 minutos. En producción puedes usar en cambio el flujo asíncrono, en el que emites, guardas el `idOperacion` y procesas el resultado cuando llega el [webhook](/v1/guias/webhooks), sin que tu proceso se quede esperando. ```javascript // Node.js 18 o superior. Ejecuta: node quickstart.mjs import { readFile, writeFile } from "node:fs/promises"; import { EcuafactClient, EcuafactApiException, esAutorizado, esFinal } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); try { // 1. Contexto: que contribuyentes puede usar tu API Key. const contexto = await client.getContexto(); const emisor = (contexto.contribuyentes ?? []).find((c) => c.puedeEmitir); if (!emisor) { throw new Error("Tu API Key no tiene un contribuyente habilitado para emitir."); } console.log(`Emisor ${emisor.identificacion}`); // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador). const comprobante = JSON.parse(await readFile("comprobante.json", "utf8")); const hoy = new Date(Date.now() - 5 * 60 * 60 * 1000); comprobante.infoTributaria.ruc = emisor.identificacion; comprobante.info.fechaEmision = `${String(hoy.getUTCDate()).padStart(2, "0")}/${String(hoy.getUTCMonth() + 1).padStart(2, "0")}/${hoy.getUTCFullYear()}`; // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key. const emision = await client.emitirFacturaEn(emisor.identificacion, comprobante, "FACTURA-2026-0001"); // codEstado es 1001 (aun sin clave de acceso) o 1002 (con claveAcceso); acepta los dos. console.log(`estado ${emision.admission.estado} codEstado ${emision.admission.codEstado} idOperacion ${emision.admission.idOperacion}`); // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min). const operacion = await client.esperarResultado(emision.admission.idOperacion); console.log(`estado ${operacion.estado} codEstado ${operacion.codEstado}`); operacion.errores.forEach((detalle) => console.log(` - ${detalle}`)); // 5. RIDE: solo existe cuando el comprobante esta autorizado. if (esAutorizado(operacion)) { const ride = await client.descargarRide(emisor.identificacion, operacion.claveAcceso); await writeFile("ride.pdf", ride.contenido); console.log(`RIDE guardado en ride.pdf; claveAcceso ${operacion.claveAcceso}`); } else if (!esFinal(operacion)) { console.log("Aun sin resultado: consulta mas tarde o espera el webhook."); } } catch (error) { if (error instanceof EcuafactApiException) { console.error(`HTTP ${error.estadoHttp} codEstado ${error.codEstado}: ${error.msgError}`); error.errores.forEach((detalle) => console.error(` - ${detalle}`)); console.error(`X-Correlation-Id: ${error.correlationId}`); } else { throw error; } } ``` ### Paso 3. Ejecuta y verifica ```bash node quickstart.mjs ``` Deberías ver algo como esto; los identificadores cambian en cada ejecución: ``` Emisor 0123456789001 estado recibido codEstado 1001 idOperacion 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f estado autorizado codEstado 2001 RIDE guardado en ride.pdf; claveAcceso 0710202601012345678900110010010000001231234567811 ``` El programa funcionó si ves `estado autorizado` y el ejemplo guardó el RIDE como `ride.pdf`. La tabla explica cada línea que puede imprimir. | Salida | Significado | Qué hacer | |---|---|---| | `estado recibido codEstado 1001` | La API aceptó la emisión y respondió `202 Accepted`. Todavía no es la autorización. La respuesta puede traer 1001, cuando aún no hay clave de acceso y `claveAcceso` es `null`, o 1002, cuando ya la trae; tu código debe aceptar los dos. Si repetiste la misma `Idempotency-Key` con el mismo cuerpo, recibes la misma operación. | Sigue con el seguimiento. Para emitir otra factura cambia `referenciaExterna` y la `Idempotency-Key`. | | `estado autorizado codEstado 2001` | El SRI autorizó el comprobante; `claveAcceso` trae la [clave de acceso](/v1/guias/glosario) real de 49 dígitos. | Descarga el RIDE o el XML. | | `estado rechazado codEstado 3001` | El SRI rechazó el comprobante. Es un rechazo fiscal, y las líneas que empiezan con `-` muestran el mensaje del SRI, que llega en `errores`. | Corrige los datos y emite un comprobante nuevo con **nueva** `Idempotency-Key`, nueva `referenciaExterna` y un secuencial nuevo. | | `estado rechazado`, `rechazo_configuracion`, `error` o `cancelado` con otro `codEstado` | La operación terminó sin autorización. | Busca el `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion) y sigue lo que indica. | | `Aun sin resultado` | Pasaron 2 minutos y el `estado` sigue en `recibido`. | Vuelve a consultar más tarde o espera el [webhook](/v1/guias/webhooks). | | `HTTP 401 codEstado 3009` | La API Key no es válida. | Revisa `ECUAFACT_API_KEY`. | | `HTTP 403 codEstado 3011` | El contribuyente o el tipo de comprobante no están habilitados, o `ruc` no coincide con el contribuyente de la ruta. | Revisa `puedeEmitir` y `tiposComprobante` en el contexto. | | `HTTP 422 codEstado 3002` | Falta un campo, un campo está mal formado o no se cumple una regla fiscal. Lee las líneas que empiezan con `-`. | Corrige el JSON; un 422 consume 1 documento como intento. | > [!NOTE] > Si ejecutas el script otro día con la misma `Idempotency-Key`, la fecha cambia > el cuerpo y la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Usa una > `Idempotency-Key` y una `referenciaExterna` nuevas para cada factura nueva. Todos los métodos `emitir` y `emitirEn` devuelven un `EmisionResultado` con estos campos: | Campo | Tipo | Descripción | |---|---|---| | `admission` | `Admission` | La respuesta de la emisión, con los mismos campos que `Operation`, que se describen en [Seguimiento y resultado](#seguimiento-y-resultado). En una emisión aceptada, `estado` es `recibido`: aceptamos el comprobante, que todavía no está autorizado. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde igual. | | `admission.codEstado` | `number` | 1001 si todavía no hay clave de acceso, con `claveAcceso` en `null`, o 1002 si ya la trae. Tu código debe aceptar los dos valores. | | `admission.idOperacion` | `string` (UUID) | Guárdalo, porque lo necesitas para el seguimiento. | | `admission.urlEstado` | `string` | URL completa del seguimiento (`https:///v1/operaciones/{idOperacion}`). | | `idempotencyKey` | `string` | La `Idempotency-Key` usada (la tuya o la que generó el SDK). Guárdala junto al documento. | | `correlationId` | `string \| undefined` | Cabecera `X-Correlation-Id` de la respuesta. Inclúyela al pedir soporte. | ## Tipo de comprobante y ruta Cada tipo de comprobante tiene su propio tipo de solicitud, igual que tiene su propio endpoint. El tipo del request que entregas fija la ruta, así que el cuerpo no lleva ningún campo de tipo y `infoTributaria` solo trae `ruc`, `estab`, `ptoEmi` y `secuencial`. Eliges el método por tipo; cada uno tiene una variante `...En` que recibe la `identificacion` de la ruta como primer argumento: | Código | Documento | Request | Emitir | Validar | Ruta de emisión | Ruta de validación | |---|---|---|---|---|---|---| | `01` | Factura | `FacturaRequest` | `emitirFactura` | `validarFactura` | `POST /v1/contribuyentes/{identificacion}/facturas` | `POST /v1/contribuyentes/{identificacion}/facturas/validar` | | `03` | Liquidación de compra | `LiquidacionCompraRequest` | `emitirLiquidacionCompra` | `validarLiquidacionCompra` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra/validar` | | `04` | Nota de crédito | `NotaCreditoRequest` | `emitirNotaCredito` | `validarNotaCredito` | `POST /v1/contribuyentes/{identificacion}/notas-credito` | `POST /v1/contribuyentes/{identificacion}/notas-credito/validar` | | `05` | Nota de débito | `NotaDebitoRequest` | `emitirNotaDebito` | `validarNotaDebito` | `POST /v1/contribuyentes/{identificacion}/notas-debito` | `POST /v1/contribuyentes/{identificacion}/notas-debito/validar` | | `06` | Guía de remisión | `GuiaRemisionRequest` | `emitirGuiaRemision` | `validarGuiaRemision` | `POST /v1/contribuyentes/{identificacion}/guias-remision` | `POST /v1/contribuyentes/{identificacion}/guias-remision/validar` | | `07` | Comprobante de retención | `RetencionRequest` | `emitirRetencion` | `validarRetencion` | `POST /v1/contribuyentes/{identificacion}/retenciones` | `POST /v1/contribuyentes/{identificacion}/retenciones/validar` | ```ts const emision = await client.emitirNotaCreditoEn(identificacion, notaCredito, "NC-2026-0001"); const validacion = await client.validarRetencion(retencion); // usa la identificacion del cliente ``` Cada request contiene solo las propiedades de su esquema del contrato, con la misma obligatoriedad y nulabilidad (`string | null` cuando el contrato admite nulo; sin `?` cuando es obligatorio). Su `info` es el tipo propio de cada documento (`InfoFactura`, `InfoLiquidacionCompra`, `InfoNotaCredito`, `InfoNotaDebito`, `InfoGuiaRemision` e `InfoComprobanteRetencion`), y sus líneas son `DetalleCompraVenta` (factura y liquidación de compra), `DetalleNotaCredito`, `Motivo`, `Destinatario` con `DetalleGuia`, o `DocsSustento` con `ImpuestoDocSustento`, `RetencionLinea` y `Pago`. Se reutilizan en todos los tipos que los comparten `InfoTributaria`, `Pago`, `Impuesto` y `CampoAdicional`. La factura conserva los nueve campos de exportación en `InfoFactura`. El SDK no tiene un tipo de comprobante genérico ni deduce el tipo por la forma del cuerpo: el método que eliges fija el tipo. El filtro `tipoDocumento` de `listarOperaciones` acepta un código (`01`) o un nombre (`factura`) y, si no es uno de los seis tipos, lanza `EcuafactTipoComprobanteException` antes de llamar a la API. ## Validar sin emitir Con `validarEn(identificacion, comprobante)` (por ejemplo `validarFacturaEn`) compruebas que un comprobante está bien armado antes de emitirlo. El método llama siempre al endpoint `/validar` del tipo: el SDK no valida nada localmente, porque las reglas de negocio de los comprobantes (campos requeridos, formatos, catálogos, topes e importes) viven solo en la API y esta puede cambiarlas sin que actualices el SDK. La API no emite nada, no consume cupo ni usa un número de la serie, y por eso el método no recibe `Idempotency-Key`. Si configuraste `identificacion` en las opciones del cliente, puedes usar `validar(comprobante)`, y la vista `client.para(identificacion)` también tiene los métodos `validar`. ```javascript // Node.js 18 o superior. Guarda como validar.mjs y ejecuta: node validar.mjs import { readFile } from "node:fs/promises"; import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const comprobante = JSON.parse(await readFile("comprobante.json", "utf8")); const validacion = await client.validarFacturaEn("0123456789001", comprobante); if (validacion.valido) { console.log("Listo para emitir"); } else { console.log(validacion.codEstado, validacion.errores); // 3002 [ '$.detalles[0].impuestos[0].valor: Valor de impuesto no coincide con base y tasa.' ] } ``` El método devuelve un objeto con `valido`, `codEstado`, `msgError`, `errores`, `advertencias` y `correlationId`. Cuando el comprobante cumple todas las reglas, la API responde 200 y el SDK lee `valido` (`true`) y `advertencias` del cuerpo: `codEstado` y `msgError` son `null`, `errores` llega vacío y `advertencias` trae los avisos que no impiden emitir, si los hay. Cuando no las cumple, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`) y el método no lanza una excepción: te devuelve `valido` en `false` y en `errores` el problema con la ruta del campo, para que lo corrijas y vuelvas a validar. Cualquier otro error se lanza igual que al emitir; por ejemplo, si el contribuyente, su RUC o el tipo de comprobante no están habilitados para tu API Key, recibes `EcuafactAuthException` con el `codEstado` 3011 (`acceso_denegado`). Como validar no tiene efectos, el SDK la reintenta ante fallos transitorios igual que una consulta. Un resultado válido significa que la emisión de ese mismo contenido no tendrá errores de validación, pero no comprueba tu cupo ni si ya emitiste ese comprobante, y no es una autorización del SRI. Los detalles están en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). ### Validar antes de emitir (opcional) Por defecto `emitir` y `emitirEn` envían el comprobante directo, con una sola petición. Si la API lo rechaza, lanzan `EcuafactValidationException` (422) con el detalle en `errores`. Si prefieres comprobar cada comprobante antes de emitirlo, activa `validarAntesDeEmitir`, que vale `false` por defecto para que en producción no se dupliquen las peticiones. Puedes activarla en el cliente o solo en una llamada: ```javascript const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY, validarAntesDeEmitir: true }); // O solo en una llamada (también sirve para desactivarla con false): const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001", { validarAntesDeEmitir: true }); console.log(r.advertencias); // avisos de /validar; si hay, no bloquean la emisión ``` Con la opción activa, cada emisión hace dos peticiones. Primero llama a `/validar`. Si `valido` es `true` y `errores` está vacío, envía la emisión y devuelve en `advertencias` los avisos que haya traído la validación. Si no es válido, lanza la misma `EcuafactValidationException` (422, `codEstado` 3002, con los `errores` de la API) **sin enviar la emisión**, así que no consume cupo. Con la opción en `false`, una sola petición. ## Seguimiento y resultado La emisión responde `202 Accepted` apenas recibe el comprobante, y el resultado del SRI llega después. Puedes conocerlo de tres formas, y combinarlas. | Forma | Método | Cuándo usarla | |---|---|---| | Consulta puntual | `getOperacion(idOperacion)` (alias `consultarOperacion`) | Un proceso programado revisa las operaciones pendientes. | | Espera activa | `esperarResultado(idOperacion, { intervaloMs, maximoMs, signal })` | Lo usas en scripts, pruebas o un proceso que puede esperar hasta 2 minutos. | | Aviso | [Webhooks](#webhooks) | En producción, recibes el resultado sin consultar. | `esperarResultado` consulta la operación cada `intervaloMs` (por defecto `5000`) hasta que `esFinal(operacion)` es `true` o pasan `maximoMs` (por defecto `120000`). **No lanza** una excepción al agotar el tiempo, sino que devuelve la última operación leída, y tú decides con `esFinal`. Si `intervaloMs` no es mayor que 0 o `maximoMs` es negativo, lanza `EcuafactSdkException`. `signal` cancela la espera y la promesa se rechaza con `signal.reason`. `idOperacion` debe ser un UUID, con guiones o como 32 caracteres hexadecimales; si no lo es, lanza `EcuafactSdkException` sin llamar a la API. ```javascript // Node.js 18 o superior. Guarda como seguimiento.mjs y ejecuta: node seguimiento.mjs import { EcuafactClient, esAutorizado, esFinal } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; // el de tu emision // Consulta puntual. const actual = await client.getOperacion(idOperacion); console.log(`ahora: ${actual.estado}`); // Espera activa: cada 3 s, maximo 60 s, cancelable con Ctrl+C. const controller = new AbortController(); process.once("SIGINT", () => controller.abort()); const operacion = await client.esperarResultado(idOperacion, { intervaloMs: 3000, maximoMs: 60000, signal: controller.signal }); if (esAutorizado(operacion)) { console.log(`Autorizado. claveAcceso ${operacion.claveAcceso}`); } else if (esFinal(operacion)) { console.log(`Termino sin autorizacion: ${operacion.estado} ${operacion.codEstado}: ${operacion.msgError}`); operacion.errores.forEach((detalle) => console.log(` - ${detalle}`)); } else { console.log("Sin resultado todavia: vuelve a consultar o espera el webhook."); } ``` Con una factura autorizada, deberías ver algo como esto: ``` ahora: autorizado Autorizado. claveAcceso 0710202601012345678900110010010000001231234567811 ``` `Operation` tiene los mismos campos de la respuesta de la API: | Campo | Tipo | Descripción | |---|---|---| | `estado` | `string` | `recibido`, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Solo `recibido` no es final. | | `codEstado` | `number` | Código numérico del resultado; su primer dígito es el `estado`. En `recibido` es 1001, sin clave de acceso, o 1002, con `claveAcceso`; en `autorizado`, 2001; y cuando no se autorizó, el código de la causa, por ejemplo 3001 (`rechazo_sri`) o 4002 (`firma_no_valida`). Compáralo con las constantes de `CodEstado`. | | `msgError` | `string \| undefined` | Descripción general y fija del código. No viene con `recibido` ni con `autorizado`. | | `errores` | `string[]` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Viene siempre y está vacío si no hay detalle. | | `idOperacion` | `string` | El identificador consultado. | | `urlEstado` | `string \| null` | URL completa del seguimiento. | | `ambiente` | `number \| null` | `1` pruebas, `2` producción. | | `tipoDocumento` | `string \| null` | Tipo de comprobante (`01`, `03`, `04`, `05`, `06`, `07`). | | `numeroDocumento` | `string \| null` | Número del comprobante, por ejemplo `001-001-000000123`. | | `referenciaExterna` | `string \| null` | La `referenciaExterna` que enviaste al emitir. | | `claveAcceso` | `string \| null` | Clave de acceso de 49 dígitos; es `null` con el `codEstado` 1001. | | `fhRecibido` | `string \| null` | Momento en que la API aceptó la emisión (ISO 8601 con zona horaria). | | `fhAutorizacion` | `string \| null` | Momento de la autorización del SRI, cuando existe. No la uses para decidir; decide con `estado`. | Qué hacer ante cada estado se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion). ## Estados tipados `Operation`, `Admission` y `Comprobante` conservan los campos de la API (`estado`, `codEstado`, `tipoDocumento`). El SDK exporta constantes y funciones para compararlos sin errores de escritura. Un valor que el SDK no conoce no rompe tu código, porque las funciones devuelven `"desconocido"`, o `null` en el caso de `tipoComprobante`, y el texto original queda en el campo. | Constante o función | Valores | |---|---| | `CodEstado` / `estadoDeCodEstado(codEstado)` | Constantes numéricas del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), con el nombre de cada código en PascalCase, por ejemplo `CodEstado.RechazoSri` (3001), `CodEstado.ComprobanteInvalido` (3002) o `CodEstado.LimiteSolicitudes` (5005). `estadoDeCodEstado` devuelve el estado que corresponde al primer dígito, incluso para un código que tu versión del SDK todavía no conoce. | | `EstadoOperacion` / `estadoOperacion(operacion)` | `Recibido` (`recibido`), `Autorizado`, `Rechazado`, `RechazoConfiguracion` (`rechazo_configuracion`), `Error`, `Cancelado`, `Desconocido` | | `TipoComprobante` / `tipoComprobante(tipoDocumento)` | `Factura` (`01`), `LiquidacionCompra` (`03`), `NotaCredito` (`04`), `NotaDebito` (`05`), `GuiaRemision` (`06`), `Retencion` (`07`); `null` si el código no se conoce | | `TipoEventoWebhook` / `tipoEventoWebhook(eventType)` | `DocumentoAutorizado` (`document.authorized`), `DocumentoRechazado` (`document.rejected`), `DocumentoFallido` (`document.failed`), `OperacionRequiereAtencion` (`operation.requires_attention`), `Desconocido` | | `EstadosPublicos` | Los valores de texto de `estado`, por ejemplo `EstadosPublicos.Recibido`. | | `esFinal(operacion)` | `true` si `estado` es cualquier valor distinto de `recibido`. Sirve también para el cuerpo de un webhook. | | `esAutorizado(operacion)` | `true` si `estado` es `autorizado`. | `estadoOperacion` acepta la operación completa, el cuerpo de un webhook o el texto del campo. ```javascript // Node.js 18 o superior. Guarda como estado.mjs y ejecuta: node estado.mjs import { CodEstado, EcuafactClient, EstadoOperacion, estadoOperacion } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const operacion = await client.getOperacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"); switch (estadoOperacion(operacion)) { case EstadoOperacion.Autorizado: console.log("Descarga el RIDE"); break; case EstadoOperacion.Recibido: console.log("Consulta mas tarde"); break; case EstadoOperacion.Rechazado: if (operacion.codEstado === CodEstado.RechazoSri) { console.log(`Corrige y emite un comprobante nuevo: ${operacion.errores.join(" | ")}`); break; } // falls through default: console.log(`Revisa codEstado ${operacion.codEstado}: ${operacion.msgError} ${operacion.errores.join(" | ")}`); } ``` ## Webhooks Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle y, antes de procesar cada entrega, comprobar que te la enviamos nosotros. Cada entrega trae dos firmas: la cabecera `Ecuafact-Signature` y las cabeceras de [Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks). `construirEventoDesdeCabeceras` acepta cualquiera de las dos. Recibe las cabeceras de la petición (`req.headers` o un `Headers` de Fetch), las comprueba contra el cuerpo **crudo** y, si alguna es válida, devuelve el evento tipado. Si ninguna coincide, está fuera de la tolerancia (300 s por defecto) o el cuerpo no es un objeto JSON, lanza `EcuafactWebhookException`. Su firma es `construirEventoDesdeCabeceras(secretos, cabeceras, cuerpo, toleranceSeconds = 300, now?)`. Si solo recibes la cabecera `Ecuafact-Signature` (`t=,v1=`), puedes usar `construirEvento(secretos, cabecera, cuerpo, toleranceSeconds = 300, now?)`, que verifica solo esa cabecera y se comporta igual. Las dos funciones aceptan un secreto o un arreglo de secretos, con o sin el prefijo `whsec_` en Standard Webhooks, y la entrega es válida si coincide con cualquiera; así puedes rotar el secreto sin rechazar entregas. Agrega el nuevo, publica tu aplicación y quita el anterior cuando las entregas lleguen firmadas con el nuevo, como se explica en [Rotación de secreto](/v1/guias/webhooks-firma#rotacion-de-secreto). El ejemplo siguiente usa el módulo `node:http`, sin dependencias. Guarda tu secreto en `ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en `ECUAFACT_WEBHOOK_SECRET_ANTERIOR`. ```javascript // Node.js 18 o superior. Guarda como webhook.mjs y ejecuta: node webhook.mjs import { createServer } from "node:http"; import { construirEventoDesdeCabeceras, EcuafactWebhookException, TipoEventoWebhook } from "@ecuafact/sdk"; const secretos = [process.env.ECUAFACT_WEBHOOK_SECRET, process.env.ECUAFACT_WEBHOOK_SECRET_ANTERIOR] .filter((s) => s); const procesados = new Set(); // en produccion, una tabla con clave unica createServer((req, res) => { if (req.method !== "POST" || req.url !== "/webhooks/ecuafact") { res.writeHead(404).end(); return; } const partes = []; req.on("data", (parte) => partes.push(parte)); req.on("end", () => { const cuerpoCrudo = Buffer.concat(partes); let evento; try { evento = construirEventoDesdeCabeceras(secretos, req.headers, cuerpoCrudo); } catch (error) { if (error instanceof EcuafactWebhookException) { res.writeHead(401).end(); return; } throw error; } // Deduplica por eventType + resourceId: una repeticion se responde 2xx sin procesar. const clave = `${evento.eventTypeRaw}|${evento.resourceId}`; if (procesados.has(clave)) { res.writeHead(200).end(); return; } procesados.add(clave); switch (evento.eventType) { case TipoEventoWebhook.DocumentoAutorizado: console.log("Autorizado", evento.idOperacion, evento.claveAcceso); break; case TipoEventoWebhook.DocumentoRechazado: console.log("Rechazo fiscal", evento.idOperacion, evento.codEstado, evento.errores); break; case TipoEventoWebhook.DocumentoFallido: console.log("No emitido", evento.idOperacion, evento.estado, evento.codEstado); break; case TipoEventoWebhook.OperacionRequiereAtencion: // Con probe es el evento de prueba del portal; si no, un aviso: el comprobante sigue // recibido (codEstado 1001 o 1002), con el motivo en errores. No reemitas. console.log("Aviso", evento.idOperacion, evento.codEstado, evento.errores, "probe =", evento.probe); break; default: console.log("Evento no reconocido", evento.eventTypeRaw); } res.writeHead(200).end(); }); }).listen(3000); ``` Para probarlo, configura el destino `https:///webhooks/ecuafact` en el portal y pulsa **Probar**. Tu servidor imprime una línea que empieza con `Aviso` y termina con `probe = true`, y responde con un 200. El SDK no administra los destinos de webhooks, solo verifica la firma y construye el evento. Los destinos los creas, listas, pausas y rotas desde el Portal del Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP o con la API REST, como se explica en [Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api). Si usas el framework Express.js, lee el cuerpo crudo solo en la ruta del webhook. ```javascript // Node.js 18 o superior con Express.js 4 o 5 (npm install express). Guarda como webhook-express.mjs import express from "express"; import { construirEventoDesdeCabeceras, EcuafactWebhookException } from "@ecuafact/sdk"; const app = express(); // express.raw entrega req.body como Buffer con los bytes tal como llegaron. app.post("/webhooks/ecuafact", express.raw({ type: "application/json" }), (req, res) => { try { const evento = construirEventoDesdeCabeceras(process.env.ECUAFACT_WEBHOOK_SECRET, req.headers, req.body); console.log(evento.eventTypeRaw, evento.resourceId); res.sendStatus(200); } catch (error) { res.sendStatus(error instanceof EcuafactWebhookException ? 401 : 500); } }); app.listen(3000); ``` > [!WARNING] > Verifica la firma sobre el cuerpo crudo. No apliques un parser JSON a la ruta > del webhook antes de `construirEventoDesdeCabeceras`, porque un JSON reconstruido no coincide > con la firma. `WebhookEvent` tiene estos campos: | Campo | Tipo | Descripción | |---|---|---| | `eventType` | `TipoEventoWebhook` | Tipo tipado; `desconocido` si el SDK no conoce el valor. | | `eventTypeRaw` | `string` | `eventType` tal como llegó. | | `resourceId` | `string` | En los eventos `document.*`, el `idOperacion`; en el evento de prueba, el identificador del destino. | | `occurredAtUtc` | `string` | Momento del evento (UTC, ISO 8601), tal como llegó; no cambia en los reintentos. | | `occurredAt` | `Date \| null` | `occurredAtUtc` convertido a `Date`; `null` si no se pudo interpretar. | | `idOperacion` | `string \| null` | Operación del comprobante. | | `estado` | `string \| null` | El mismo `estado` del seguimiento: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`, y `recibido` en el aviso `operation.requires_attention`. | | `ruc` | `string \| null` | Identificación del contribuyente emisor. Sirve para enrutar un destino compartido por varios contribuyentes; es `null` en el evento de prueba. | | `tipoDocumento` | `string \| null` | Tipo de comprobante (`01` a `07`), cuando el evento lo trae. | | `claveAcceso` | `string \| null` | Clave de acceso del comprobante. | | `codEstado` | `number \| null` | Código numérico del resultado, por ejemplo 2001 en `document.authorized`, 3001 (`rechazo_sri`) en `document.rejected` o 4002 (`firma_no_valida`) en `document.failed`. Decide con `estado` y `codEstado`, no solo con `eventType`. | | `msgError` | `string \| null` | Descripción fija del código; `null` cuando no hay error. | | `errores` | `string[]` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacío si no hay detalle. | | `fhAutorizacion` | `string \| null` | Momento de la autorización del SRI, cuando existe. | | `probe` | `boolean` | `true` en el evento de prueba del portal. | | `cuerpo` | `Record` | Cuerpo completo ya interpretado, incluidos campos que el SDK no tipa. | Si solo necesitas saber si la firma es válida, usa `verificarWebhook(secretos, cabeceras, cuerpo, now?, toleranceSeconds?)`, que acepta cualquiera de las dos firmas, o `verify(secretos, cabecera, cuerpo, now?, toleranceSeconds?)`, que comprueba solo `Ecuafact-Signature`. Ambas devuelven `boolean` y nunca lanzan una excepción; aceptan un secreto o un arreglo, y el cuerpo como `string`, `Buffer` o `Uint8Array`. `verificarStandardWebhooks(secretos, { webhookId, webhookTimestamp, webhookSignature }, cuerpo)` comprueba solo la firma de Standard Webhooks. Para tus pruebas automatizadas, `sign(secreto, segundosUnix, cuerpo)` calcula una cabecera `Ecuafact-Signature` válida. Qué hacer ante cada evento está en [Webhooks](/v1/guias/webhooks), y el algoritmo de la firma, en [Verificación de firma](/v1/guias/webhooks-firma). ## Errores Todas las excepciones del SDK heredan de `EcuafactSdkException`, que extiende `Error`, y las que vienen de una respuesta de la API heredan además de `EcuafactApiException`. Pregunta primero por las específicas y al final por `EcuafactApiException` o `EcuafactSdkException`. | Excepción | Hereda de | Cuándo ocurre | Qué hacer | |---|---|---|---| | `EcuafactConfigurationException` | `EcuafactSdkException` | Falta la API Key o la URL, la URL no es HTTPS, tiene usuario, consulta o fragmento, o termina en `/v1`, la API Key tiene espacios o caracteres de control, una opción del cliente o de `RequestOptions` es inválida, o un constructor de comprobantes recibe una escala o un modo de redondeo inválido. | Corrige la configuración. No llama a la API. | | `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API, o la respuesta se cortó, tras agotar los intentos. También se lanza cuando la API responde con éxito (2xx) pero el cuerpo no es JSON válido. | Reintenta más tarde con la misma `idempotencyKey`. Si estabas emitiendo, repite la emisión con esa clave para recuperar su resultado sin duplicar el comprobante. | | `EcuafactTimeoutException` | `EcuafactSdkException` | Se agotó `timeoutMs` en el último intento o `totalTimeoutMs` de la llamada. | Reintenta con la misma `idempotencyKey`; si emitías, consulta antes el seguimiento. | | `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida, o cuerpo que no es un objeto JSON. | Responde 401 y no proceses el evento. | | `EcuafactAuthException` | `EcuafactApiException` | HTTP 401 o 403, con el `codEstado` 3009 (`credenciales_invalidas`), 3010 (`ip_no_autorizada`) o 3011 (`acceso_denegado`). | Corrige la API Key, registra la IP o revisa que el contribuyente y el tipo estén habilitados. | | `EcuafactValidationException` | `EcuafactApiException` | HTTP 400 o 422, con el `codEstado` 3002 (`comprobante_invalido`), 3003 (`solicitud_invalida`), 3007 (`version_no_soportada`) o 3012 (`filtros_invalidos`). | Corrige según `errores`. Un 422 consume 1 documento como intento. | | `EcuafactNotFoundException` | `EcuafactApiException` | HTTP 404, con el `codEstado` 3013 (`no_encontrado`), o sin `codEstado` si la ruta no existe y la respuesta no trae cuerpo de error. | Verifica el `idOperacion`, la `claveAcceso` o la identificación. | | `EcuafactConflictException` | `EcuafactApiException` | HTTP 409, con el `codEstado` 3004 (`comprobante_duplicado`), 3005 (`conflicto_idempotencia`) o 3014 (`correo_no_disponible`). | Mira el `codEstado` en la tabla de códigos de abajo. | | `EcuafactRateLimitException` | `EcuafactApiException` | HTTP 429 con un `codEstado` distinto de 4004, normalmente 5005 (`limite_solicitudes`). | Espera `retryAfterMs` y reintenta con la misma `idempotencyKey`. El SDK ya lo reintenta por defecto, así que la excepción llega cuando se agotan los intentos o si desactivaste `retryRateLimited`. | | `EcuafactQuotaException` | `EcuafactApiException` | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`). | Amplía el cupo ([`GET /v1/consumo`](/v1/guias/consumo)). No reintentes. | | `EcuafactServerException` | `EcuafactApiException` | HTTP 5xx, con el `codEstado` 5001 (`error_interno`), 5002 (`servicio_no_disponible`), 5003 (`error_dependencia`) o 5004 (`tiempo_agotado`), tras agotar los intentos si el estado es reintentable. | Si `esReintentable` es `true`, reintenta más tarde con la misma `idempotencyKey`. Un 501 no se reintenta. | | `EcuafactApiException` | `EcuafactSdkException` | Cualquier otro estado de error de la API, por ejemplo 413 con el `codEstado` 3006 (`cuerpo_excedido`). | Revisa `codEstado`, `msgError` y `errores`. | | `EcuafactTipoComprobanteException` | `EcuafactSdkException` | El filtro `tipoDocumento` de `listarOperaciones` no es uno de los seis tipos. | Usa un código (`01`) o un nombre (`factura`), como se explica en [Tipo de comprobante](#tipo-de-comprobante-y-ruta). No llama a la API. | | `EcuafactResponseTooLargeException` | `EcuafactSdkException` | El cuerpo de la respuesta supera el tope `maxResponseBytes`. Trae `limite` y `bytesLeidos`. | Sube el tope o desactívalo si esperas archivos más grandes. No se reintenta. | | `EcuafactSdkException` | `Error` | Otros errores locales: `Idempotency-Key` inválida, `idOperacion` que no es UUID, importe con formato inválido, `identificacion` que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, `.` o `..`, uso incorrecto de un constructor de comprobantes (un `Date` inválido, `linea` antes de `destinatario` o datos del documento sustento antes de `docSustento`), falta el contribuyente por defecto, parámetro obligatorio vacío o respuesta no reconocida. | Corrige la llamada. | | Propiedad de `EcuafactApiException` | Tipo | Descripción | |---|---|---| | `codEstado` | `number \| undefined` | Código numérico del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), por ejemplo 3002 o 3004. Úsalo para decidir, comparándolo con las constantes de `CodEstado`. `undefined` si la respuesta no trae cuerpo de error. | | `estado` | `string \| undefined` | `estado` de la respuesta de error, como `rechazado`, `rechazo_configuracion` o `error`; si no llegó, el que indica el primer dígito de `codEstado`. | | `msgError` | `string \| undefined` | Descripción general y fija del código. Muéstrala o regístrala, pero no la uses para decidir. | | `estadoHttp` | `number` | Estado HTTP. | | `errores` | `string[]` | Detalle específico del error, como la ruta del campo que falla en un 3002. Vacío cuando no hay detalle. | | `correlationId` | `string \| undefined` | Cabecera `X-Correlation-Id`. Inclúyelo al pedir soporte. | | `idempotencyKey` | `string \| undefined` | Clave usada en la emisión; reutilízala al reintentar. | | `retryAfterMs` | `number \| null` | Espera indicada por la cabecera `Retry-After`, en milisegundos; `null` si no llegó. | | `esReintentable` | `boolean` | `true` si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el `codEstado` 5005. El 429 con 4004 (cupo agotado) no es reintentable. | Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción conserva la `Idempotency-Key` y el correlativo de la solicitud; repite la emisión con esa misma clave y no se duplica el comprobante. En Node.js, esa excepción es `EcuafactConnectionException`, que se lanza cuando el cuerpo no es JSON y trae la clave en `idempotencyKey` y el `X-Correlation-Id` en `correlationId`. `EcuafactConnectionException` y `EcuafactTimeoutException` traen `idempotencyKey`, `correlationId` (el de la respuesta o, si no llegó, el que enviaste en `RequestOptions`) y la causa original en `cause`. ```javascript // Node.js 18 o superior. Guarda como errores.mjs y ejecuta: node errores.mjs import { readFile } from "node:fs/promises"; import { EcuafactClient, EcuafactApiException, EcuafactConnectionException, EcuafactQuotaException, EcuafactRateLimitException, EcuafactTimeoutException, EcuafactValidationException } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const comprobante = JSON.parse(await readFile("comprobante.json", "utf8")); try { const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001"); console.log(r.admission.estado, r.admission.idOperacion); } catch (error) { if (error instanceof EcuafactValidationException) { // Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual. error.errores.forEach((detalle) => console.error(detalle)); } else if (error instanceof EcuafactQuotaException) { console.error("Cupo agotado: compra un paquete. No reintentes."); } else if (error instanceof EcuafactRateLimitException) { console.error(`Limite de solicitudes: espera ${error.retryAfterMs ?? 1000} ms y reintenta con ${error.idempotencyKey}.`); } else if (error instanceof EcuafactApiException) { console.error(error.estadoHttp, error.codEstado, error.msgError, error.errores, "reintentable =", error.esReintentable, "correlation =", error.correlationId); } else if (error instanceof EcuafactConnectionException || error instanceof EcuafactTimeoutException) { // Sin conexion o sin respuesta: reintenta mas tarde con la MISMA Idempotency-Key. console.error(error.message, "clave =", error.idempotencyKey); } else { throw error; } } ``` Estos son los códigos que verás con más frecuencia. El catálogo completo, con el nombre de cada código, está en [Errores](/v1/guias/errores#catalogo-de-codestado), y las constantes de `CodEstado` llevan ese mismo nombre, escrito con la convención del lenguaje. | `codEstado` | Nombre | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---|---| | 3009 | `credenciales_invalidas` | 401 | API Key ausente o inválida. | Corrige la API Key. No reintentes sin cambiar nada. | | 3010 | `ip_no_autorizada` | 403 | La IP no está permitida o no se pudo identificar. | Registra tu IP en **Cuenta > IP permitidas** o llama directo a la URL de la API, sin proxies intermedios; si persiste, contacta a soporte con el `correlationId`. | | 3011 | `acceso_denegado` | 403 | Contribuyente o tipo de comprobante no habilitado, `ruc` distinto del contribuyente de la ruta, o sin paquete de documentos vigente. | Revisa `getContexto()` (`puedeEmitir`, `tiposComprobante`). | | 5005 | `limite_solicitudes` | 429 | Superaste el límite de solicitudes por minuto. | Espera `retryAfterMs` y reintenta con la misma `Idempotency-Key`, aunque el SDK ya lo hace por defecto; reduce el ritmo. | | 3003 | `solicitud_invalida` | 400 | Cabeceras inválidas (por ejemplo, `Idempotency-Key`) o JSON mal formado. | Corrige según `errores`. | | 3002 | `comprobante_invalido` | 422 | Campos del comprobante faltantes o mal formados, campos desconocidos o de otro tipo, o una regla fiscal incumplida (totales, impuestos). | Corrige según `errores`; consume 1 documento como intento. | | 3012 | `filtros_invalidos` | 400 | Filtro de consulta fuera de rango (fechas o `max`) o valor no admitido. | Ajusta los filtros. | | 3006 | `cuerpo_excedido` | 413 | Cuerpo mayor a 2 MiB en la emisión o 1 MiB en otros `POST`/`PUT`. | Reduce el cuerpo. | | 3004 | `comprobante_duplicado` | 409 | Ya existe un comprobante con ese número recibido, autorizado o rechazado por el SRI. | No reenvíes; si querías otro comprobante, usa otro `secuencial` u omítelo para que se asigne el siguiente. | | 3005 | `conflicto_idempotencia` | 409 | Misma `Idempotency-Key` o `referenciaExterna` con otro contenido. | Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. | | 4004 | `cupo_agotado` | 429 | Se agotó el cupo de documentos. El SDK no lo reintenta. | Revisa `getConsumo()`; compra un paquete. | | 3013 | `no_encontrado` | 404 | Operación, comprobante, catálogo o RIDE no encontrado. | Verifica el id o la clave; el RIDE existe solo si está autorizado. | | 5001, 5002, 5003, 5004 | `error_interno`, `servicio_no_disponible`, `error_dependencia`, `tiempo_agotado` | 500, 503, 502, 504 | Error interno, servicio no disponible, o el servicio de validación fiscal falló o no respondió. | El SDK ya reintentó; vuelve a intentar más tarde con la misma `Idempotency-Key`. | ## Idempotencia y reintentos La `Idempotency-Key` evita emitir dos veces el mismo comprobante si una llamada se repite, por ejemplo después de un timeout o de una caída de la red. - Si no la pasas, el SDK genera un UUID sin guiones, lo usa en todos sus reintentos y te la devuelve en `resultado.idempotencyKey` o, si falla, en `error.idempotencyKey`. - Te recomendamos pasar un valor estable por intención, como tu número interno de factura, o un UUID v4 que guardes junto al documento. - El SDK valida la clave antes de enviarla con la misma regla de la API: de 1 a 128 caracteres, solo letras, dígitos y `-` `_` `.` `:` `/`. Si no cumple, lanza `EcuafactSdkException` sin llamar a la API. > [!WARNING] > Si reintentas una emisión desde tu aplicación, reutiliza la misma > `Idempotency-Key`. Una clave nueva para el mismo comprobante puede duplicar la > emisión. | Situación | Se reintenta | Detalle | |---|---|---| | HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con `retryableStatusCodes`. Solo en `GET` y en `POST`/`PUT` con `Idempotency-Key` (la emisión siempre la lleva). | | HTTP 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí, salvo con `retryRateLimited: false` | Espera lo que indica `Retry-After` y reintenta. Con `retryRateLimited: false` lanza `EcuafactRateLimitException` con `retryAfterMs`, y decides tú cuándo reintentar. | | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`) | Nunca | Esperar no repone el cupo. Lanza `EcuafactQuotaException`. | | Error de red o timeout de un intento | Sí | Se reintenta en las mismas condiciones; al agotar los intentos lanza `EcuafactConnectionException` o `EcuafactTimeoutException`. | | Consultas (`getContexto`, `getOperacion`, descargas de RIDE/XML, `getConsumo`, perfil, consultas SRI) | Sí | Se reintentan porque son `GET`. | | `validar` y `validarEn` | Sí | No llevan `Idempotency-Key`, pero se reintentan porque validar no tiene efectos. | | `actualizarPerfil`, `actualizarLogo` | No | No llevan `Idempotency-Key`, así que un reintento automático podría repetir el efecto. | | Cualquier otro 4xx | No | Se lanza la excepción de inmediato. | Entre intentos, el SDK espera `retryBaseDelayMs` x intento con `linear` o `retryBaseDelayMs` x 2^(intento-1) con `exponential`. A esa espera le suma un margen aleatorio de hasta `retryJitterMs` x intento con `linear` y de hasta `retryJitterMs` con `exponential`. Si la respuesta trae un `Retry-After` mayor y `respectRetryAfter` es `true`, espera ese tiempo. La espera nunca supera `maxRetryDelayMs`. Si con `totalTimeoutMs` configurado la siguiente espera superaría el tope, el SDK no reintenta y lanza el error del último intento. ## Opciones por llamada Puedes cambiar el tiempo máximo, el tope total, la correlación, la información adicional, los reintentos o la cancelación de una sola llamada sin tocar la configuración del cliente. Todos los métodos que llaman a la API aceptan un último parámetro opcional `opciones?: RequestOptions`. También lo aceptan `esperarResultado` (como tercer parámetro) y los métodos de la vista `client.para(...)`. Lo que no indiques se toma de la configuración del cliente. | Campo | Tipo | Qué hace | |---|---|---| | `timeoutMs` | `number` | Tiempo máximo de cada intento, en milisegundos. Reemplaza `timeoutMs` del cliente solo en esta llamada. Mayor que 0. | | `totalTimeoutMs` | `number` | Tope de toda la llamada, incluidos reintentos y esperas, en milisegundos. Con `0` no hay límite. Al superarlo rechaza con `EcuafactTimeoutException`. | | `correlationId` | `string` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres `A-Z a-z 0-9 . _ -`. | | `additionalInfo` | `string` | Se envía en la cabecera `X-Additional-Info` solo en esta llamada y reemplaza el `additionalInfo` del cliente. Con `null` o sin valor usa el del cliente, y con `""` no envía la cabecera en esta llamada. Sigue las mismas reglas que la opción del cliente, descritas en [Información adicional](#informacion-adicional). | | `reintentos` | `boolean` | `false` desactiva los reintentos solo en esta llamada. `true` no los reactiva si el cliente tiene `retryTransientFailures: false`. | | `signal` | `AbortSignal` | Cancela la llamada en curso y las esperas entre reintentos. La promesa se rechaza con `signal.reason` (`AbortError` por defecto). | | `validarAntesDeEmitir` | `boolean` | Solo en `emitir` y `emitirEn`. Reemplaza el valor del cliente en esta llamada, tanto para activarlo como para desactivarlo. | La API devuelve la correlación que enviaste. La encuentras en `resultado.correlationId` de la emisión, en `correlationId` de `EcuafactApiException` y en `correlationId` de `EcuafactTimeoutException` y `EcuafactConnectionException`. Si la API no devuelve la cabecera, se usa la que enviaste. ```javascript // Node.js 18 o superior. Guarda como opciones.mjs y ejecuta: node opciones.mjs import { writeFile } from "node:fs/promises"; import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY, additionalInfo: "MiERP/4.2" // cabecera X-Additional-Info en cada solicitud }); // Un solo intento y correlacion propia para esta consulta. const contexto = await client.getContexto({ reintentos: false, correlationId: "pedido-2026-0457", additionalInfo: "MiERP/4.2 sucursal=norte" // reemplaza al del cliente solo aqui }); console.log(`Contribuyentes: ${contexto.contribuyentes?.length ?? 0}`); // Mas tiempo para una descarga grande, con tope total y cancelacion a los 90 s. const controller = new AbortController(); const temporizador = setTimeout(() => controller.abort(), 90_000); try { const ride = await client.descargarRide( "0123456789001", "0710202601012345678900110010010000001231234567811", { timeoutMs: 60_000, totalTimeoutMs: 120_000, signal: controller.signal } ); await writeFile("ride.pdf", ride.contenido); } finally { clearTimeout(temporizador); } ``` Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu emisor. Si pasas un valor inválido, la promesa se rechaza con `EcuafactConfigurationException` sin llamar a la API. Pasa, por ejemplo, con un `correlationId` con espacios o de más de 64 caracteres, con un `additionalInfo` fuera de sus reglas, con un `timeoutMs` menor o igual a 0, con un `totalTimeoutMs` negativo o con un `signal` que no es un `AbortSignal`. Si cancelas una emisión, no sabes si la API la recibió. Reintenta después con la **misma** `Idempotency-Key` y el mismo cuerpo. Si ya se había recibido, la API responde con el mismo `idOperacion` y el estado actual de la operación. En `esperarResultado(idOperacion, opciones, llamada)` el tercer parámetro se aplica a cada consulta; si `opciones.signal` no está, se usa `llamada.signal` para cancelar también la espera. ## Información adicional Puedes enviar un dato tuyo en cada solicitud, por ejemplo la versión de tu ERP o la sucursal que emite, para que ubiquemos tus llamadas cuando nos pidas soporte. Viaja en la cabecera `X-Additional-Info`; la API la asocia a tu solicitud y no cambia su respuesta. Es la única cabecera personalizada que admite el SDK. Las reglas de la API están en [Límites](/v1/guias/limites#cabeceras). | Dónde | Qué hace | |---|---| | `additionalInfo` en las opciones del cliente | Se envía en todas las solicitudes del cliente, incluidas las consultas de `esperarResultado`, los reintentos y la vista `client.para(...)`. Sin valor o con `""`, no se envía. | | `additionalInfo` en `RequestOptions` | Reemplaza el valor del cliente solo en esa llamada. Sin valor o con `null` usa el del cliente, y con `""` no envía la cabecera en esa llamada. | El SDK valida el valor en tu proceso, antes de llamar a la API, con estas reglas: - Solo caracteres ASCII imprimibles (0x20 a 0x7E): sin tildes, `ñ` ni saltos de línea. - Sin espacios al inicio ni al final. - Máximo 256 caracteres. Si no cumple, el SDK lanza `EcuafactConfigurationException` sin llamar a la API. El valor no aparece en `console.log`, `util.inspect` ni `JSON.stringify` de las opciones. No pongas en él la API Key ni datos personales. ```javascript // Node.js 18 o superior. Guarda como info-adicional.mjs y ejecuta: node info-adicional.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY, additionalInfo: "erp=MiERP/4.2; sucursal=001" }); // Todas las solicitudes llevan X-Additional-Info: erp=MiERP/4.2; sucursal=001 const contexto = await client.getContexto(); // Solo esta llamada lleva otro valor. await client.getConsumo({ additionalInfo: "erp=MiERP/4.2; sucursal=002; lote=2026-10-08" }); // Esta llamada no envia la cabecera. await client.getConsumo({ additionalInfo: "" }); console.log(`Contribuyentes: ${contexto.contribuyentes?.length ?? 0}`); ``` | Error | Por qué pasa | Qué hacer | |---|---|---| | `EcuafactConfigurationException` al crear el cliente | `additionalInfo` tiene tildes, `ñ`, saltos de línea u otro carácter fuera de 0x20 a 0x7E, espacios al inicio o al final, o más de 256 caracteres. | Corrige el valor: quita tildes y espacios de los extremos y acórtalo. | | La promesa de una llamada se rechaza con `EcuafactConfigurationException` | El mismo problema en `additionalInfo` de `RequestOptions`. No se llamó a la API. | Corrige el valor de esa llamada. | ## Proxy, TLS y tiempo de conexión Si necesitas salir por un proxy, confiar en una CA corporativa o limitar el tiempo de conexión, puedes pasar un `dispatcher` de `undici`, la biblioteca en la que se apoya el `fetch` de Node.js. Instálala en tu proyecto con `npm install undici` y pasa también el `fetch` de `undici`, para que el `dispatcher` y el `fetch` sean de la misma versión sin depender de la que trae tu Node.js. ```javascript // Node.js 18 o superior. Guarda como proxy.mjs y ejecuta: node proxy.mjs import { fetch, ProxyAgent } from "undici"; import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY, fetch, dispatcher: new ProxyAgent("http://proxy.miempresa.local:8080"), retryBackoff: "exponential", retryBaseDelayMs: 500, retryRateLimited: true, totalTimeoutMs: 60000 }); console.log((await client.getContexto()).contribuyentes?.length ?? 0); ``` Para una CA corporativa o un tiempo de conexión propio, usa `new Agent({ connect: { ca, timeout: 10000 } })` de `undici` como `dispatcher`, donde `ca` es el contenido PEM del certificado, por ejemplo `readFileSync("ca-corporativa.pem")`. ## Constructores de comprobantes Puedes armar la [Estructura del comprobante](/v1/guias/emision) con métodos en lugar de escribir el JSON. `ComprobanteBuilder` es opcional y solo ayuda a armar el cuerpo: produce el mismo request de su tipo (`FacturaRequest`, `NotaCreditoRequest`...) que armas a mano, sin calcular, sin completar valores y sin lanzar por reglas de negocio. Los campos requeridos, los formatos, los catálogos, los topes y los importes los valida únicamente la API; para comprobarlos usa [`validar`](#validar-sin-emitir) o [`validarAntesDeEmitir`](#validar-antes-de-emitir-opcional). Todo valor que asignes se envía tal cual. ```javascript // Node.js 18 o superior. Guarda como constructor.mjs y ejecuta: node constructor.mjs import { ComprobanteBuilder, EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); // Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor. const comprobante = ComprobanteBuilder.factura("0123456789001", "001", "001") .referencias("MiERP", "FACTURA-2026-0002") .fechaEmision(new Date()) // se formatea en hora de Ecuador .comprador("07", "9999999999999", "CONSUMIDOR FINAL") .linea("SERV-001", "Servicio de prueba", 1, "10.00", 0, { codigoPorcentaje: "4", tarifa: 15 }) .pago("01", "11.50") .construir(); const validacion = await client.validarFacturaEn("0123456789001", comprobante); // la API decide console.log(validacion.valido, validacion.errores, validacion.advertencias); const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0002", { correlationId: "pedido-2026-0458" }); console.log(r.admission.estado, r.admission.idOperacion, r.correlationId); ``` Si la API acepta el comprobante, deberías ver `true [] []` y luego `recibido pedido-2026-0458`. Si ejecutas el script otro día con la misma `Idempotency-Key`, la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`); en ese caso usa una `Idempotency-Key` y una `referenciaExterna` nuevas. | Tipo | Entrada | Métodos propios | |---|---|---| | Factura (`01`) | `ComprobanteBuilder.factura(ruc, estab, ptoEmi)` | `comprador(tipo, identificacion, razonSocial, direccion?)`, `linea`, `propina`, `moneda`, `pago(formaPago, total?, plazo?, unidadTiempo?)` | | Liquidación de compra (`03`) | `ComprobanteBuilder.liquidacionCompra(...)` | `proveedor(tipo, identificacion, razonSocial, direccion?)`, `linea`, `moneda`, `pago` | | Nota de crédito (`04`) | `ComprobanteBuilder.notaCredito(...)` | `comprador`, `documentoModificado(codDocModificado, numDocModificado, fecha, totalDocumentoSustento?)`, `motivo(texto)`, `linea` (con `codigoInterno`), `moneda` | | Nota de débito (`05`) | `ComprobanteBuilder.notaDebito(...)` | `comprador`, `documentoModificado(codDocModificado, numDocModificado, fecha)`, `iva(tarifa)`, `motivo(razon, valor)`, `pago` | | Guía de remisión (`06`) | `ComprobanteBuilder.guiaRemision(...)` | `traslado(dirPartida, fechaIni, fechaFin)`, `transportista(tipo, identificacion, razonSocial, placa)`, `destinatario(identificacion, razonSocial, direccion, motivoTraslado, opciones?)`, `linea(codigoInterno, descripcion, cantidad, opciones?)` | | Retención (`07`) | `ComprobanteBuilder.retencion(...)` | `sujetoRetenido(tipo, identificacion, razonSocial)`, `periodoFiscal("MM/yyyy")`, `parteRelacionada(boolean)`, `docSustento({...})`, `impuestoDocSustento(...)`, `retencion(codigo, codigoRetencion, base, porcentaje, valor?)`, `pago(formaPago, total?)` | Todos los constructores tienen además `referencias(origen, externa)`, `secuencial`, `dirEstablecimiento`, `infoAdicional(nombre, valor)`, `info({...})` (asigna campos del `Info*` de su tipo tal cual) y `construir()`, que devuelve una copia independiente. `fechaEmision` acepta un texto `dd/MM/yyyy` o un `Date`, que se formatea en la hora de Ecuador, y existe en todos salvo la guía de remisión, que usa `traslado`. Algunos métodos tienen reglas propias: - En `linea(codigo, descripcion, cantidad, precioUnitario, descuento?, iva?, opciones?)`, `descuento` es un importe en dólares e `iva` un objeto `{ codigoPorcentaje, tarifa }` como los acepta la API, por ejemplo `{ codigoPorcentaje: "4", tarifa: 15 }`. El séptimo parámetro lleva el ICE y otros datos de la línea, por ejemplo `linea(..., { codigoPorcentaje: "4", tarifa: 15 }, { ice: { codigoPorcentaje: "3011", tarifa: 10 } })`; también acepta `codigoAuxiliar`, `precioTotalSinImpuesto` y `detallesAdicionales` (en la nota de crédito, `codigoAdicional` en lugar de `codigoAuxiliar`). `linea(detalle)` con un objeto agrega la línea tal cual. - En la guía de remisión, `linea` agrega el bien al **último** destinatario, así que llama antes a `destinatario(...)`; si no, lanza `EcuafactSdkException`. - En la retención, `impuestoDocSustento`, `retencion` y `pago` se aplican al **último** documento sustento, así que llama antes a `docSustento(...)`; si no, lanza `EcuafactSdkException`. `docSustento` envía `pagoLocExt` solo si lo indicas. Los importes que das como texto decimal (`"11.50"`) se envían como número JSON literal, sin pasar por `number`, para no perder precisión. ### Reglas de negocio solo en la API Las reglas de negocio de los comprobantes viven solo en la API, de modo que un cambio de regla no te obliga a actualizar el SDK. Por eso el SDK no calcula totales ni valida reglas fiscales; solo valida localmente lo que evita una petición mal construida: la identificación, la `claveAcceso` y los UUID de la ruta, el tipo de documento que elige el método, la `Idempotency-Key`, que `pagina` y `tamanoPagina` sean enteros, y la firma de los webhooks. Los importes con formato inválido, como `"10,50"`, lanzan `EcuafactSdkException` porque no se pueden serializar sin perder precisión. ## Métodos `` es `Factura`, `LiquidacionCompra`, `NotaCredito`, `NotaDebito`, `GuiaRemision` o `Retencion`, y cada combinación es un método propio (por ejemplo `emitirNotaDebito` o `validarGuiaRemisionEn`). Todos los métodos devuelven una `Promise`, salvo `para`, que devuelve la vista del contribuyente. La identificación que reciben es siempre el valor `identificacion` del contexto. Todos los que llaman a la API aceptan `opciones?: RequestOptions` como último parámetro. | Método | Endpoint | Devuelve | |---|---|---| | `getContexto()` | `GET /v1/contexto` | `Contexto` | | `emitir(comprobante, idempotencyKey?)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}` (ver [Tipo de comprobante y ruta](#tipo-de-comprobante-y-ruta)) | `EmisionResultado` | | `emitirEn(identificacion, comprobante, idempotencyKey?)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` | | `validar(comprobante)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionComprobante` (ver [Validar sin emitir](#validar-sin-emitir)) | | `validarEn(identificacion, comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionComprobante` | | `listarOperaciones(filtro?)` | `GET /v1/operaciones` | `PaginaComprobantes` (ver [Listado de operaciones](#listado-de-operaciones)) | | `getSalud()` | `GET /salud` | `Salud` (`status` y `cuerpo`) | | `getEstadoServicio()` | `GET /estado` | `EstadoServicio` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)). No envía la API Key. | | `listarCatalogos()` | `GET /v1/catalogos` | `Catalogos` | | `getCatalogo(nombre)` | `GET /v1/catalogos/{nombre}` | `CatalogoDetalle` | | `getOperacion(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation`. `idOperacion` debe ser un UUID. | | `consultarOperacion(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias) | | `esperarResultado(idOperacion, { intervaloMs?, maximoMs?, signal? }, llamada?)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída (ver [Seguimiento y resultado](#seguimiento-y-resultado)). | | `descargarRide(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | `ArchivoComprobante` (PDF) | | `descargarXml(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | `ArchivoComprobante` (XML del comprobante autorizado) | | `getConsumo()` | `GET /v1/consumo` | `QuotaBucket` | | `getPerfil(identificacion)` | `GET /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` | | `actualizarPerfil(identificacion, cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` | | `actualizarLogo(identificacion, contenido, contentType, nombreArchivo)` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (ver [Logo del perfil](#logo-del-perfil)) | | `consultarContribuyente(identificacion, fusionar = true, fuente?)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta` | | `buscarContribuyentes(apellidos, nombres?, clase?, max?)` | `GET /v1/consultas/contribuyentes` | `BusquedaContribuyente[]` | | `listarEstablecimientos(ruc, filtro?)` | `GET /v1/consultas/establecimientos/{ruc}` | `EstablecimientosContribuyente`. `filtro` acepta `Todos`, `SoloActivos`, `SoloCerrados`, `SoloMatriz` o `SoloSucursales`. | | `validarIdentificacion(numero)` | `GET /v1/consultas/identificacion/validar/{numero}` | `ValidacionIdentificacion` (revisa `valido`) | | `decodificarClaveAcceso(claveAcceso)` | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | `ClaveAccesoDecodificada` | | `para(identificacion)` | - (no llama a la API) | `EcuafactContribuyente` (ver [Varios contribuyentes](#varios-contribuyentes)) | | `construirEventoDesdeCabeceras(...)`, `construirEvento(...)`, `verificarWebhook(...)`, `verificarStandardWebhooks(...)`, `verify(...)` y `sign(...)` | - (funciones exportadas, locales) | `WebhookEvent`, `boolean` o `string` (ver [Webhooks](#webhooks)) | Ten en cuenta además estos detalles de los métodos y de sus tipos: - Los métodos `emitir` y `emitirEn` no validan el contenido del comprobante: lo envían y propagan el 422 de la API como `EcuafactValidationException`. - Si no configuras `identificacion` en las opciones del cliente, `emitir` y `validar` lanzan `EcuafactSdkException`. En ese caso usa `emitirEn`, `validarEn` o `client.para(...)`. - `ArchivoComprobante` tiene `contenido` (`Uint8Array`) y `contentType`. Las descargas solo existen con el comprobante autorizado; ver [Descargar XML](/v1/guias/consulta-xml). - `QuotaBucket` tiene `limiteDocumentos`, `reservados`, `consumidos`, `disponibles`, `vigenteHasta` y los campos `...Extra`, que se mantienen por compatibilidad y valen 0, que se explican en [Consumo](/v1/guias/consumo). Cada comprobante autorizado o rechazado consume un documento de tu cupo, y uno cancelado lo libera. - `actualizarPerfil` recibe solo los campos editables: `nombreComercial`, `direccionMatriz`, `correo`, `telefono`, `ciudad` y `provincia`, descritos en [Perfil del emisor](/v1/guias/perfil-emisor). ## Importes exactos En JavaScript un `number` es binario, y por eso `0.1 + 0.2` da `0.30000000000000004`. Para enviar importes exactos, los campos de importe, cantidad, precio y tarifa de la solicitud aceptan `number` o `string` (tipo `Importe`). Un texto decimal con punto, como `"11.50"`, se envía como número JSON literal (`11.50`), sin pasar por `number`. Un texto con otro formato (por ejemplo `"10,50"`) se rechaza con `EcuafactSdkException` antes de llamar a la API. Los campos `valor` de `infoAdicional` y `detallesAdicionales` son texto y se envían como texto. ```javascript // Node.js 18 o superior. Guarda como importes.mjs y ejecuta: node importes.mjs import { readFile } from "node:fs/promises"; import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const comprobante = JSON.parse(await readFile("comprobante.json", "utf8")); // Calcula en centavos enteros y envia el resultado como texto con 2 decimales. const baseCentavos = 1000; // 10.00 const ivaCentavos = Math.round(baseCentavos * 15 / 100); // 1.50 comprobante.info.totalSinImpuestos = (baseCentavos / 100).toFixed(2); // "10.00" comprobante.info.importeTotal = ((baseCentavos + ivaCentavos) / 100).toFixed(2); // "11.50" const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001"); console.log(r.admission.estado, r.admission.idOperacion); ``` En las respuestas, los importes (por ejemplo `Comprobante.total`) llegan como `number`. En TypeScript, si lees un importe de tu propio request (por ejemplo `FacturaRequest`) para calcular, su tipo es `number | string | null`, así que conviértelo con `Number(...)`. Las reglas de cálculo de cada comprobante están en [Factura](/v1/guias/emision-01). ## Varios contribuyentes Si no configuras `identificacion` en las opciones, usa los métodos `...En` o una vista por contribuyente. La vista repite la identificación por ti en cada método. ```javascript // Node.js 18 o superior. Guarda como perfil.mjs y ejecuta: node perfil.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const matriz = client.para("0123456789001"); const perfil = await matriz.getPerfil(); console.log(perfil.razonSocial, perfil.identificacion); ``` La vista `EcuafactContribuyente` tiene estos métodos, y todos aceptan `RequestOptions` al final. | Método | Equivale a | |---|---| | `emitir(comprobante, idempotencyKey?)` | `client.emitirEn(identificacion, comprobante, idempotencyKey)` | | `validar(comprobante)` | `client.validarEn(identificacion, comprobante)` | | `descargarRide(claveAcceso)` | `client.descargarRide(identificacion, claveAcceso)` | | `descargarXml(claveAcceso)` | `client.descargarXml(identificacion, claveAcceso)` | | `getPerfil()` | `client.getPerfil(identificacion)` | | `actualizarPerfil(cambios)` | `client.actualizarPerfil(identificacion, cambios)` | | `actualizarLogo(contenido, contentType, nombreArchivo)` | `client.actualizarLogo(identificacion, ...)` | | `esperarResultado(idOperacion, opciones?, llamada?)` | `client.esperarResultado(idOperacion, opciones, llamada)` | | `listarOperaciones(filtro?)` | `client.listarOperaciones({ identificacion, ...filtro })` | | `getConsumo()` | `client.getConsumo()` (el cupo es de la API Key, no del contribuyente) | ## Logo del perfil Con `actualizarLogo` puedes subir el logo que aparece en el RIDE de tu contribuyente sin armar la petición `multipart/form-data`; recibes el `PerfilEmisor` actualizado. Acepta PNG o JPEG de hasta 512 KB; el contenido puede ser `Uint8Array` (incluido `Buffer`), `ArrayBuffer` o `Blob`. Si el contenido está vacío o falta `contentType` o `nombreArchivo`, lanza `EcuafactSdkException` sin llamar a la API. La subida no se reintenta automáticamente. ```javascript // Node.js 18 o superior. Guarda como logo.mjs y ejecuta: node logo.mjs import { readFile } from "node:fs/promises"; import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const perfil = await client.actualizarLogo("0123456789001", await readFile("logo.png"), "image/png", "logo.png"); console.log(`Logo actualizado para ${perfil.razonSocial}: ${perfil.logo}`); ``` Las reglas del archivo y los errores posibles están en [Perfil del emisor](/v1/guias/perfil-emisor). ## Listado de operaciones `listarOperaciones` devuelve una página de los comprobantes emitidos de un contribuyente (`GET /v1/operaciones`) y no consume cupo. `identificacion` es obligatoria (si no la indicas, usa la `identificacion` del cliente); los demás filtros son opcionales: `desde` y `hasta` en formato `yyyy-MM-dd`, `tipoDocumento` (el código o el nombre del tipo), `buscar` (número, clave de acceso, contraparte o referencia), `pagina` desde 1 y `tamanoPagina` de 1 a 100. Si un filtro no tiene el formato esperado, el SDK lanza `EcuafactSdkException` sin llamar a la API. ```js let pagina = 1; for (;;) { const resultado = await client.listarOperaciones({ identificacion: "0123456789001", desde: "2026-11-01", hasta: "2026-11-30", pagina, tamanoPagina: 50 }); for (const fila of resultado.comprobantes) { console.log(fila.numeroDocumento, fila.estado, fila.codEstado, fila.total); } if (!resultado.hayMas) break; pagina += 1; } ``` La respuesta trae `comprobantes`, `pagina`, `tamanoPagina` y `hayMas`; mientras `hayMas` sea `true`, pide la página siguiente. Cada fila incluye `claveAcceso`, `numeroDocumento`, `tipoDocumento`, `fechaEmision`, `identificacionContraparte`, `razonSocialContraparte`, `total`, `estado`, `codEstado`, `msgError`, `errores` y `fhAutorizacion`. La vista `client.para(identificacion)` ofrece el mismo método con la identificación fija. Para comprobar que el servicio responde, `getSalud()` llama a `GET /salud` (sin API Key) y devuelve el código HTTP y el cuerpo; si la respuesta no es 2xx, lanza la excepción correspondiente. ## Consultas SRI Con estos métodos puedes consultar el catastro del SRI, y no consumen cupo. ```javascript // Node.js 18 o superior. Guarda como sri.mjs y ejecuta: node sri.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const validacion = await client.validarIdentificacion("0123456789001"); const contribuyente = await client.consultarContribuyente("0123456789001"); const encontrados = await client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10); const establecimientos = await client.listarEstablecimientos("0123456789001", "SoloActivos"); console.log(validacion.valido, contribuyente.razonSocial, encontrados.length, establecimientos); ``` `fuente` admite `Todas`, el valor por defecto, o `SriCatastro`; `clase` admite `PersonaNatural`, el valor por defecto, `Sociedad` o `SociedadPublica`; y el `filtro` de establecimientos admite valores como `SoloActivos`. Un valor no admitido hace que la API responda 400 con el `codEstado` 3012 (`filtros_invalidos`), que el SDK lanza como `EcuafactValidationException`. Los parámetros y las respuestas de cada consulta están en [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). ## Estado del servicio y catálogos `getEstadoServicio` lee el estado público del servicio, el mismo que describe [Estado del servicio](/v1/guias/estado-del-servicio) (`GET /estado`), y no envía la API Key ni consume cupo. `listarCatalogos` devuelve el índice de catálogos del SRI, con la clave (`nombre`) y una descripción de cada uno. `getCatalogo` recibe esa clave y devuelve las filas del catálogo. Estas dos consultas usan tu API Key y tampoco consumen cupo. Si la clave no existe, el SDK lanza `EcuafactNotFoundException`. Los catálogos cambian pocas veces al año, así que puedes guardar la respuesta en caché por una hora. `getEstadoServicio` devuelve un `EstadoServicio`: | Campo | Tipo | Descripción | |---|---|---| | `estado` | `string` | Estado global: `operativo`, `degradado`, `caido` o `sin_datos`. | | `medidoEn` | `string \| null \| undefined` | Momento de la última medición (ISO 8601). Es `null` mientras no hay mediciones. | | `componentes` | `ComponenteEstado[]` | Componentes monitoreados, cada uno con `nombre` y `estado` (mismos valores que el estado global). | | `disponibilidad90Dias` | `number \| null \| undefined` | Porcentaje de minutos sin caída en los últimos 90 días. Es `null` si aún no hay muestras. | | `incidentes` | `IncidentePublico[]` | Incidentes de los últimos 90 días y los abiertos, del más reciente al más antiguo. Arreglo vacío si no hubo ninguno. | | `incidentes[].inicio` | `string` | Inicio del incidente (ISO 8601). | | `incidentes[].fin` | `string \| null \| undefined` | Fin del incidente. Falta mientras sigue abierto. | | `incidentes[].impacto` | `string` | `degradado` o `caido`. | | `incidentes[].titulo` | `string` | Título breve. | | `incidentes[].detalle` | `string \| null \| undefined` | Qué significó para las integraciones. Falta si no hay detalle. | `listarCatalogos` devuelve un objeto `Catalogos` y `getCatalogo`, un `CatalogoDetalle`: | Campo | Tipo | Descripción | |---|---|---| | `catalogos` | `CatalogoResumen[]` | Catálogos disponibles, cada uno con `nombre` (la clave que recibe `getCatalogo`) y `descripcion`. | | `nombre` | `string` | Clave del catálogo, en `CatalogoDetalle`. | | `descripcion` | `string` | Descripción breve, en `CatalogoDetalle`. | | `fuente` | `string` | Tabla o anexo de la ficha técnica del SRI de donde proviene. | | `items` | `CatalogoItem[]` | Filas del catálogo. | | `items[].codigo` | `string` | Código tal como va en el comprobante. | | `items[].descripcion` | `string` | Descripción del código. | | `items[].valor` | `number \| null \| undefined` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. Falta si el catálogo no lo tiene. | | `items[].vigenteDesde` | `string \| null \| undefined` | Primer día de vigencia, en formato `yyyy-MM-dd`. Falta si no está acotada por el inicio. | | `items[].vigenteHasta` | `string \| null \| undefined` | Último día de vigencia, en formato `yyyy-MM-dd`. Falta si sigue vigente. | | `items[].atributos` | `Record \| null \| undefined` | Atributos propios del catálogo. Falta si no hay. | ```javascript // Node.js 18 o superior. Guarda como catalogos.mjs y ejecuta: node catalogos.mjs import { EcuafactClient } from "@ecuafact/sdk"; const client = new EcuafactClient({ baseAddress: "https://api-sandbox.mynexusapi.com/", apiKey: process.env.ECUAFACT_API_KEY }); const estado = await client.getEstadoServicio(); console.log(estado.estado, estado.disponibilidad90Dias, estado.incidentes.length); const { catalogos } = await client.listarCatalogos(); console.log(catalogos.map((c) => c.nombre)); const tarifas = await client.getCatalogo("tarifas-iva"); for (const fila of tarifas.items) { console.log(fila.codigo, fila.descripcion, fila.valor); } ``` El significado de cada catálogo y de sus códigos está en [Catálogos](/v1/guias/catalogos#consultar-los-catalogos-por-api). ## Siguientes pasos - [Factura](/v1/guias/emision-01): revisa todos los campos y las reglas de cálculo para construir tus comprobantes. - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta qué significa cada `estado` y cada `codEstado`. - [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI sin consultar en bucle. - [Visión general de los SDK](/v1/guias/sdk): compara los cinco SDK y decide entre SDK o HTTP directo. --- # SDK Python Biblioteca oficial para emitir comprobantes desde Python 3.10 o superior, seguir su autorización, descargar el RIDE y verificar webhooks. Si desarrollas en Python, puedes integrarte con nuestros servicios de facturación usando nuestro SDK para Python. Lo instalas desde PyPI y, en lugar de armar cada petición HTTP, llamas a métodos como `emitir_en` o `descargar_ride`, que reciben y devuelven modelos tipados con los importes como `Decimal`. Puedes reintentar sin miedo a duplicar comprobantes, porque el SDK reutiliza la `Idempotency-Key` en sus reintentos; además envía tu API Key en cada llamada, te indica si llegaste al límite de solicitudes o si se agotó tu cupo, y verifica la firma de los webhooks que te enviamos. Esta guía sigue el orden de una integración. Primero instalas el paquete, configuras el cliente, emites tu primera factura y sigues su resultado; después recibes webhooks y manejas errores, y al final ajustas los reintentos y la conexión y armas comprobantes con los constructores. La referencia de métodos está al final. Si todavía no decides entre el SDK y la API por HTTP directo, compáralos en [SDKs](/v1/guias/sdk). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan > `https://api-sandbox.mynexusapi.com`; cambia a `https://api.mynexusapi.com` > solo cuando emitas comprobantes reales. ## 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: ```text Instala el SDK Python de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. 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/sdk-python.md antes de escribir código; no inventes campos. Reutiliza el lenguaje, el gestor de paquetes y la estructura del proyecto; si no hay proyecto, crea uno mínimo. Instala con pip install ecuafact. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Requiere Python 3.10 o superior. 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 programa e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer. ``` ## Paquete | Dato | Valor | |---|---| | Paquete PyPI | [`ecuafact`](https://pypi.org/project/ecuafact/) | | Versión | `1.0.1` | | Python | 3.10 o superior. | | Dependencias | `httpx` 0.27 o superior y `pydantic` 2.6 o superior, que se instalan solas. | | Cliente | Es síncrono y usa `httpx.Client`. Úsalo como context manager (`with`) o llama a `close()` al terminar. Incluye anotaciones de tipos (`py.typed`). | ## Requisitos - [ ] Python 3.10 o superior, que compruebas con `python --version`. - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, crea tu sandbox como se explica en [Sandbox de pruebas](/v1/guias/sandbox). - [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier IP. En producción, la IP desde la que ejecutas el código debe estar en **Cuenta > IP permitidas**; si no lo está, la API responde 403 con el `codEstado` 3010 (`ip_no_autorizada`). ## Instalación Usa un entorno virtual para no mezclar dependencias. ```bash python -m venv .venv source .venv/bin/activate # en Windows: .venv\Scripts\activate pip install ecuafact # o, con la versión fija: pip install "ecuafact==1.0.1" ``` En `requirements.txt`, escribe `ecuafact==1.0.1`. Después comprueba la instalación. ```bash python -c "import ecuafact; print(ecuafact.__version__)" ``` La instalación funcionó si el comando imprime `1.0.1`. ## Configuración Crea el cliente **una vez** y reutilízalo, porque sirve para todos los [contribuyentes](/v1/guias/glosario) de tu API Key. ```python import os from ecuafact import EcuafactClient, EcuafactClientOptions client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], identificacion="0123456789001", # opcional: contribuyente por defecto )) print(client.options) # la API Key no aparece client.close() ``` Si no pasas `api_key`, el SDK lee la variable de entorno `ECUAFACT_API_KEY`, y si no pasas `base_address`, lee `ECUAFACT_BASE_URL`. Con las dos variables definidas basta `EcuafactClient()`. Los nombres están en las constantes `ENV_API_KEY` y `ENV_BASE_URL`, que se importan de `ecuafact`. Eliges el ambiente con la URL que configuras, porque el SDK no tiene una opción aparte para eso. Usa `https://api-sandbox.mynexusapi.com/` para pruebas y `https://api.mynexusapi.com/` para producción, **sin** `/v1`, ya que el SDK agrega la versión a cada ruta. | Opción | Tipo | Valor por defecto | Descripción | |---|---|---|---| | `base_address` | `str \| None` | `ECUAFACT_BASE_URL` | URL absoluta `https`, sin usuario ni contraseña, sin consulta, sin fragmento y sin `/v1`. El SDK rechaza `http://`. | | `api_key` | `str \| None` | `ECUAFACT_API_KEY` | Tu API Key; viaja en la cabecera `X-Api-Key`. Solo caracteres ASCII imprimibles, sin espacios al inicio o al final. No aparece en `repr`. | | `identificacion` | `str \| None` | `None` | Contribuyente por defecto para `emitir` y `validar` sin identificación. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). | | `timeout` | `float \| httpx.Timeout` | `30.0` | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta, en segundos. Mayor que 0. Para descargas grandes, súbelo en el cliente o en una sola llamada con `RequestOptions(timeout=...)`. | | `connect_timeout` | `float \| None` | `None` (igual a `timeout`) | Tiempo máximo para abrir la conexión, en segundos. Mayor que 0. | | `max_response_bytes` | `int \| None` | 32 MiB (`33554432`); 100 MiB (`104857600`) en las descargas de RIDE y XML | Tope en bytes del cuerpo de una respuesta. Un entero lo aplica a todas las llamadas, incluidas las descargas; `None` o `0` lo desactiva. Al superarlo lanza `EcuafactResponseTooLargeException` con `limite` y `bytes_leidos`. | | `total_timeout` | `float \| None` | `None` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas, en segundos. Mayor que 0. El detalle está en [Idempotencia y reintentos](#idempotencia-y-reintentos). | | `user_agent` | `str` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. | | `additional_info` | `str \| None` | `None` (no se envía) | Texto libre de tu integración que viaja en la cabecera `X-Additional-Info` de cada solicitud. No aparece en `repr`, y sus reglas están en [Información adicional](#informacion-adicional). | | `validar_antes_de_emitir` | `bool` | `False` | Si es `True`, `emitir` y `emitir_en` llaman primero a `/validar` y no envían la emisión cuando la API responde `valido: false` (ver [Validar antes de emitir](#validar-antes-de-emitir-opcional)). Cada emisión hace dos peticiones, así que déjalo en `False` en producción salvo que lo necesites. | | `retry_transient_failures` | `bool` | `True` | Reintenta fallos transitorios. `False` desactiva todo reintento. | | `max_attempts` | `int` | `3` | Intentos por solicitud, incluido el primero. Entero 1 o mayor. | | `retry_status_codes` | `Collection[int] \| None` | `None` = 408, 425, 500, 502, 503, 504 | Estados HTTP que se reintentan (entre 100 y 599). El 429 no va aquí: lo controla `retry_rate_limited`. Los valores por defecto están en `DEFAULT_RETRYABLE_STATUS_CODES`. | | `retry_rate_limited` | `bool` | `True` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`). El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. | | `respect_retry_after` | `bool` | `True` | Espera lo que indique la cabecera `Retry-After` antes de reintentar, si es mayor que la espera calculada. | | `retry_base_delay_ms` | `float` | `200.0` | Espera base entre reintentos, en milisegundos. 0 o mayor. | | `retry_backoff` | `RetryBackoff \| str` | `RetryBackoff.LINEAR` | `"linear"` o `"exponential"`. Las fórmulas están en [Idempotencia y reintentos](#idempotencia-y-reintentos). | | `retry_jitter_ms` | `float` | `50.0` | Variación aleatoria que se suma a cada espera, en milisegundos. 0 o mayor. | | `max_retry_delay_ms` | `int` | `60000` | Espera máxima entre reintentos, en milisegundos. Con `0` no hay tope. | | `http_client` | `httpx.Client \| None` | `None` | Tu propio `httpx.Client`, para controlar el proxy, TLS o el pool. El SDK no lo cierra. No se combina con `transport`, `proxy` ni `verify`, así que configúralos en ese cliente. | | `transport` | `httpx.BaseTransport \| None` | `None` | Transporte de `httpx` alternativo, útil para pruebas con `httpx.MockTransport`. No se combina con `proxy` ni `verify`. | | `proxy` | `str \| httpx.Proxy \| None` | `None` | Proxy del cliente, por ejemplo `http://proxy.miempresa.local:8080`. | | `verify` | `bool \| str \| ssl.SSLContext \| None` | `None` (verificación normal) | Verificación TLS del cliente interno. Acepta un booleano, la ruta a un bundle de CA o un `ssl.SSLContext`. | ```python EcuafactClientOptions(max_response_bytes=64 * 1024 * 1024) # 64 MiB; None desactiva el tope ``` Las opciones se validan al crear el cliente. El constructor lanza `EcuafactConfigurationException`, antes de hacer cualquier llamada, en cualquiera de estos casos: - Falta la API Key o la URL. - La URL no es una URL HTTPS absoluta, trae usuario, consulta o fragmento, o termina en `/v1`. - La API Key tiene espacios o caracteres no válidos. - `max_attempts` es menor que 1. - Un tiempo (`timeout`, `connect_timeout`, `total_timeout`) no es mayor que 0. - `max_response_bytes` no es un entero mayor que 0, `0` ni `None`. - Una espera (`retry_*_ms`, `max_retry_delay_ms`) es negativa. - `additional_info` no cumple su formato. - Combinas `http_client` o `transport` con `proxy` o `verify`. El mensaje de la excepción nunca incluye la API Key. ## Quickstart: de la API Key al RIDE Este script hace el flujo completo en el ambiente de pruebas: lee tu [contexto](/v1/guias/consulta-contexto), emite una factura, espera el resultado del SRI con el [seguimiento](/v1/guias/consulta-operacion) y descarga el [RIDE](/v1/guias/glosario), el PDF del comprobante. ### Paso 1. Guarda el comprobante Guarda este JSON como `comprobante.json` junto al script. Es una factura a consumidor final, con el tipo de identificación `07` y la identificación `9999999999999`, que solo se admite en facturas de hasta 50.00. Factura 10.00 más el IVA del 15 %, que son 1.50, por un total de 11.50. No lleva `secuencial`, porque te asignamos el siguiente [secuencial](/v1/guias/glosario) de la serie `estab`-`ptoEmi`. El script reemplaza `ruc` por el de tu contexto y `fechaEmision` por la fecha de hoy. ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "07", "identificacionComprador": "9999999999999", "razonSocialComprador": "CONSUMIDOR FINAL", "totalSinImpuestos": 10.00, "totalDescuento": 0.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "baseImponible": 10.00, "valor": 1.50 } ], "propina": 0.00, "importeTotal": 11.50, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 11.50 } ] }, "detalles": [ { "codigoPrincipal": "SERV-001", "descripcion": "Servicio de prueba", "cantidad": 1, "precioUnitario": 10.00, "descuento": 0.00, "precioTotalSinImpuesto": 10.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 10.00, "valor": 1.50 } ] } ] } ``` El cuerpo no lleva el tipo de documento: en el script lo lees con `FacturaRequest`, y ese modelo elige el endpoint de facturas, como se explica en [Tipo de comprobante](#tipo-de-comprobante). `estab` y `ptoEmi` deben ser un [establecimiento](/v1/guias/glosario) y un [punto de emisión](/v1/guias/glosario) de tu emisor; el sandbox crea el establecimiento `001` con el punto de emisión `001`. Cada campo está explicado en [Factura](/v1/guias/emision-01). Si prefieres armar el comprobante con métodos en lugar de JSON, usa los [constructores](#constructores-de-comprobantes). ### Paso 2. Escribe el script Guarda el código siguiente como `quickstart.py`. Los modelos del SDK usan nombres en `snake_case` (`info_tributaria`, `fecha_emision`) y aceptan el JSON de la API con sus nombres originales (`infoTributaria`, `fechaEmision`). Los importes del JSON se leen como `Decimal`. El paso 4 del script usa `esperar_resultado`, un método **opcional** que consulta la operación cada 5 segundos hasta tener un resultado final o hasta 2 minutos. En producción puedes usar en cambio el flujo asíncrono, en el que emites, guardas el `id_operacion` y procesas el resultado cuando llega el [webhook](#webhooks). Así tu proceso no se queda esperando. ```python import os import json from datetime import datetime, timedelta, timezone from ecuafact import EcuafactApiException, EcuafactClient, EcuafactClientOptions, FacturaRequest opciones = EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], ) with EcuafactClient(opciones) as client: try: # 1. Contexto: que contribuyentes puede usar tu API Key. contexto = client.get_contexto() emisor = next(c for c in contexto.contribuyentes if c.puede_emitir) print(f"Emisor {emisor.identificacion}") # 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador). with open("comprobante.json", encoding="utf-8") as archivo: comprobante = FacturaRequest.model_validate(json.load(archivo)) comprobante.info_tributaria.ruc = emisor.identificacion comprobante.info.fecha_emision = datetime.now(timezone(timedelta(hours=-5))).strftime("%d/%m/%Y") # 3. Emision: 202 Accepted. Guarda id_operacion e Idempotency-Key. emision = client.emitir_en(emisor.identificacion, comprobante, "FACTURA-2026-0001") # cod_estado es 1001 (aun sin clave de acceso) o 1002 (con clave_acceso); acepta los dos. print(f"estado {emision.admission.estado} codEstado {emision.admission.cod_estado} idOperacion {emision.admission.id_operacion}") # 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min). operacion = client.esperar_resultado(emision.admission.id_operacion) print(f"estado {operacion.estado} codEstado {operacion.cod_estado}") for detalle in operacion.errores: print(f" - {detalle}") # 5. RIDE: solo existe cuando el comprobante esta autorizado. if operacion.es_autorizado: ride = client.descargar_ride(emisor.identificacion, operacion.clave_acceso) with open("ride.pdf", "wb") as salida: salida.write(ride.contenido) print(f"RIDE guardado en ride.pdf; claveAcceso {operacion.clave_acceso}") elif not operacion.es_final: print("Aun sin resultado: consulta mas tarde o espera el webhook.") except EcuafactApiException as error: print(f"HTTP {error.estado_http} codEstado {error.cod_estado}: {error.msg_error}") for detalle in error.errores: print(f" - {detalle}") print(f"X-Correlation-Id: {error.correlation_id}") ``` ### Paso 3. Ejecuta y verifica ```bash python quickstart.py ``` Deberías ver algo como esto; los identificadores cambian en cada ejecución: ``` Emisor 0123456789001 estado recibido codEstado 1001 idOperacion 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f estado autorizado codEstado 2001 RIDE guardado en ride.pdf; claveAcceso 0710202601012345678900110010010000001231234567811 ``` El programa funcionó si ves `estado autorizado` y el ejemplo guardó el RIDE como `ride.pdf`. La tabla explica cada línea que puede imprimir. | Salida | Significado | Qué hacer | |---|---|---| | `estado recibido codEstado 1001` | La API aceptó la emisión y respondió `202 Accepted`. Todavía no es la autorización. La respuesta puede traer 1001, cuando aún no hay clave de acceso y `clave_acceso` es `None`, o 1002, cuando ya la trae; tu código debe aceptar los dos. Si repetiste la misma `Idempotency-Key` con el mismo cuerpo, recibes la misma operación. | Sigue con el seguimiento. Para emitir otra factura cambia `referenciaExterna` y la `Idempotency-Key`. | | `estado autorizado codEstado 2001` | El SRI autorizó el comprobante; `clave_acceso` trae la [clave de acceso](/v1/guias/glosario) de 49 dígitos. | Descarga el RIDE o el XML. | | `estado rechazado codEstado 3001` | El SRI rechazó el comprobante. Es un rechazo fiscal, y las líneas que empiezan con `-` muestran el mensaje del SRI, que llega en `errores`. | Corrige los datos y emite un comprobante nuevo con **nueva** `Idempotency-Key`, nueva `referenciaExterna` y un secuencial nuevo. | | `estado rechazado`, `rechazo_configuracion`, `error` o `cancelado` con otro `codEstado` | La operación terminó sin autorización. | Sigue la fila de su `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion). | | `Aun sin resultado` | Pasaron 2 minutos y el `estado` sigue en `recibido`. | Vuelve a consultar más tarde con `get_operacion` o espera el [webhook](#webhooks). No emitas otra vez. | | `HTTP 401 codEstado 3009` | La API Key no es válida. | Revisa `ECUAFACT_API_KEY`. | | `HTTP 422 codEstado 3002` | Falta un campo, un campo está mal formado o no se cumple una regla fiscal. Lee las líneas que empiezan con `-`. | Corrige el JSON; un 422 consume 1 documento como intento. | > [!NOTE] > Si ejecutas el script otro día con la misma `Idempotency-Key`, la fecha cambia > el cuerpo y la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Usa una > `Idempotency-Key` y una `referenciaExterna` nuevas para cada factura nueva. ## Tipo de comprobante Así como la API tiene un endpoint por tipo de documento, el SDK tiene un modelo de solicitud por tipo, y el tipo del modelo que pasas elige la ruta. El cuerpo no lleva un campo de tipo y los métodos no reciben un argumento `tipo`. | Modelo | Documento | Ruta de emisión | Modelos de su cuerpo | |---|---|---|---| | `FacturaRequest` | Factura (`01`) | `.../facturas` | `InfoFactura`, `DetalleCompraVenta` | | `LiquidacionCompraRequest` | Liquidación de compra (`03`) | `.../liquidaciones-compra` | `InfoLiquidacionCompra`, `DetalleCompraVenta` | | `NotaCreditoRequest` | Nota de crédito (`04`) | `.../notas-credito` | `InfoNotaCredito`, `DetalleNotaCredito` | | `NotaDebitoRequest` | Nota de débito (`05`) | `.../notas-debito` | `InfoNotaDebito`, `Motivo` | | `GuiaRemisionRequest` | Guía de remisión (`06`) | `.../guias-remision` | `InfoGuiaRemision`, `Destinatario`, `DetalleGuia` | | `RetencionRequest` | Comprobante de retención (`07`) | `.../retenciones` | `InfoComprobanteRetencion`, `DocsSustento`, `RetencionLinea`, `ImpuestoDocSustento` | Los seis modelos reutilizan `InfoTributaria`, `Pago`, `Impuesto` y `CampoAdicional` cuando el contrato los comparte. Cada modelo tiene exactamente las propiedades de su esquema, con su nulabilidad. Las propiedades que el contrato marca como obligatorias llevan `Obligatorio.` en su descripción (`Field.description`, y `json_schema_extra={"obligatorio": True}`) y el editor las muestra con autocompletado, pero el SDK no las exige: puedes crear el modelo con cualquier combinación de propiedades sin que se lance una excepción local. Lo que construyes se envía tal cual, incluida una propiedad que el contrato no define (por ejemplo, un nombre mal escrito), y la API responde `422` con `codEstado` 3002 y el detalle en `errores`. La lectura de las respuestas sí es permisiva: un campo nuevo de la API no rompe tu código. ```python emision = client.emitir_en(identificacion, factura, "FACTURA-2026-0001") # factura es un FacturaRequest validacion = client.validar_en(identificacion, nota_credito) # nota_credito es un NotaCreditoRequest ``` `emitir`, `emitir_en`, `validar` y `validar_en` (también en la vista `client.para(...)`) aceptan solo estos seis modelos. Si tienes un JSON o un `dict`, conviértelo con el modelo de su tipo: `FacturaRequest.model_validate(datos)`. Cualquier otro objeto lanza `EcuafactTipoComprobanteException` antes de llamar a la API. Los [constructores](#constructores-de-comprobantes) devuelven directamente el modelo de su tipo. El filtro `tipo_documento` de [`listar_operaciones`](#listado-de-operaciones) es distinto: filtra el listado y acepta un `TipoComprobante`, su nombre (`"factura"`, `"liquidacion"`, `"nota-credito"`, `"nota-debito"`, `"guia"`, `"retencion"`) o su código (`"01"` a `"07"`). ## Validar sin emitir Antes de emitir puedes comprobar que un comprobante cumple las reglas de la API. `validar_en(identificacion, comprobante)` llama siempre al endpoint `/validar` del tipo: el SDK no valida nada localmente, porque las reglas de negocio de los comprobantes (campos requeridos, formatos, catálogos, topes e importes) viven solo en la API y esta puede cambiarlas sin que actualices el SDK. La llamada no emite nada, no consume cupo ni lleva `Idempotency-Key`, así que puedes llamarlo tantas veces como necesites mientras corriges el documento. Usa la ruta del tipo del modelo (ver [Tipo de comprobante](#tipo-de-comprobante)) con `/validar` al final, como se detalla en [Métodos](#metodos). Si configuraste `identificacion` en las opciones del cliente, usa `validar(comprobante)`, y en una vista por contribuyente, `client.para(identificacion).validar(comprobante)`. Las tres formas aceptan `opciones=RequestOptions(...)` por nombre. El método devuelve un `ValidacionResultado` con `valido`, `cod_estado`, `msg_error`, `errores`, `advertencias` y `correlation_id`. Cuando la API responde 200, `valido` es `True`, `cod_estado` y `msg_error` son `None` y `errores` llega vacío. Cuando el comprobante incumple una regla, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`) y el SDK no lanza una excepción: devuelve `valido` en `False` y en `errores` el mismo detalle que recibirías al emitir. Las `advertencias` son avisos que no impiden emitir, y llegan tanto con 200 como con 422. ### Validar antes de emitir (opcional) Por defecto `emitir` y `emitir_en` envían el comprobante directo, con una sola petición. Si la API lo rechaza, lanzan `EcuafactValidationException` (422) con el detalle en `errores`. Si prefieres comprobar cada comprobante antes de emitirlo, activa `validar_antes_de_emitir`, que vale `False` por defecto para que en producción no se dupliquen las peticiones. Puedes activarla en el cliente o solo en una llamada: ```python client = EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], validar_antes_de_emitir=True, )) # O solo en una llamada (también sirve para desactivarla con False): r = client.emitir_en( "0123456789001", comprobante, "FACTURA-2026-0001", opciones=RequestOptions(validar_antes_de_emitir=True), ) print(r.advertencias) # avisos de /validar; si hay, no bloquean la emisión ``` Con la opción activa, cada emisión hace dos peticiones. Primero llama a `/validar`. Si `valido` es `True` y `errores` está vacía, envía la emisión y devuelve en `advertencias` los avisos que haya traído la validación. Si no es válido, lanza la misma `EcuafactValidationException` (422, `cod_estado` 3002, con los `errores` de la API) **sin enviar la emisión**, así que no consume cupo. Con la opción en `False`, una sola petición. ```python # Guarda como validar.py. Instala: pip install ecuafact. Ejecuta: python validar.py import json import os from ecuafact import EcuafactClient, EcuafactClientOptions, FacturaRequest with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: with open("comprobante.json", encoding="utf-8") as archivo: comprobante = FacturaRequest.model_validate(json.load(archivo)) resultado = client.validar_en("0123456789001", comprobante) if resultado.valido: print("Comprobante valido: ya puedes emitirlo.") else: print(f"codEstado {resultado.cod_estado}: {resultado.msg_error}") for detalle in resultado.errores: print(f" - {detalle}") ``` Reemplaza `0123456789001` por el valor `identificacion` de tu contribuyente en `GET /v1/contexto`. Si el comprobante tiene un impuesto mal calculado, el programa imprime algo como esto: ``` comprobante_invalido: Comprobante invalido. - $.detalles[0].impuestos[0].valor: Valor de impuesto no coincide con base y tasa. ``` Cualquier otra respuesta lanza la misma excepción que el resto de los métodos. Por ejemplo, si el contribuyente, su RUC o el tipo de comprobante no están habilitados para tu API Key, la API responde 403 con el `codEstado` 3011 (`acceso_denegado`) y recibes `EcuafactAuthException`. Como la validación no tiene efectos, el SDK la reintenta ante errores transitorios igual que una consulta, según lo que configuraste en [Idempotencia y reintentos](#idempotencia-y-reintentos). Un comprobante válido todavía puede fallar al emitirlo, porque la validación no revisa tu cupo ni si ya emitiste ese documento. El detalle completo está en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir) de la guía de emisión. ## Seguimiento del resultado La emisión responde `202 Accepted` con una **operación**, lo que significa que el comprobante quedó recibido pero el SRI todavía no lo autorizó. Puedes conocer el resultado de tres formas. | Forma | Método | Cuándo usarla | |---|---|---| | Consulta puntual | `get_operacion(id_operacion)` (alias `consultar_operacion`) | Tu sistema consulta cuando lo necesita, por ejemplo desde un job periódico o un botón "Actualizar". | | Espera en el proceso | `esperar_resultado(id_operacion, intervalo=5.0, maximo=120.0)` | La usas en scripts, pruebas o procesos que pueden esperar hasta tener el resultado. | | Sin consultar | [Webhooks](#webhooks) | En producción, recibes el resultado en tu servidor apenas existe. | `esperar_resultado` consulta la operación cada `intervalo` segundos y se detiene en cuanto `es_final` es `True` o cuando pasan `maximo` segundos. Devuelve **siempre** la última `Operation` leída y, si se agotó el tiempo, no lanza una excepción, así que revisa `es_final` y `es_autorizado`. Un `intervalo` menor o igual a 0, un `maximo` negativo o un `id_operacion` que no es UUID lanzan `EcuafactSdkException` sin llamar a la API. Si pasas `opciones=RequestOptions(...)`, se aplican a **cada** consulta; por eso `total_timeout` acota cada consulta y no la espera completa, que la acota `maximo`. ```python import os from ecuafact import EcuafactClient, EcuafactClientOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: # Consulta puntual. operacion = client.get_operacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f") print(operacion.estado, operacion.cod_estado, operacion.clave_acceso) # Espera: cada 10 s, como maximo 5 minutos. operacion = client.esperar_resultado("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", intervalo=10, maximo=300) if operacion.es_autorizado: print("Autorizado:", operacion.clave_acceso) elif operacion.es_final: print("Terminado sin autorizacion:", operacion.estado, operacion.cod_estado, operacion.msg_error, operacion.errores) else: print("Aun sin resultado; vuelve a consultar mas tarde") ``` `Operation` tiene los mismos campos que [Seguimiento de una operación](/v1/guias/consulta-operacion), en `snake_case`. | Campo | Tipo | Descripción | |---|---|---| | `estado` | `str \| None` | `recibido`, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Solo `recibido` no es final. | | `cod_estado` | `int \| None` | Código numérico del resultado (`codEstado`); su primer dígito es el `estado`. En `recibido` es 1001, sin clave de acceso, o 1002, con `clave_acceso`; en `autorizado`, 2001; y cuando no se autorizó, el código de la causa, por ejemplo 3001 (`rechazo_sri`) o 4002 (`firma_no_valida`). Compáralo con las constantes de `CodEstado`. | | `msg_error` | `str \| None` | Descripción general y fija del código. `None` con `recibido` y `autorizado`. | | `errores` | `list[str]` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Lista vacía si no hay detalle. | | `id_operacion` | `str` | UUID de la operación. | | `url_estado` | `str \| None` | URL completa del seguimiento. | | `ambiente` | `int \| None` | `1` pruebas, `2` producción. | | `tipo_documento` | `str \| None` | Tipo de comprobante (`01`, `03`, `04`, `05`, `06`, `07`). | | `numero_documento` | `str \| None` | Número del comprobante, por ejemplo `001-001-000000123`. | | `referencia_externa` | `str \| None` | La `referenciaExterna` que enviaste al emitir. | | `clave_acceso` | `str \| None` | Clave de acceso de 49 dígitos; es `None` con el `codEstado` 1001. | | `fh_recibido` | `str \| None` | Momento en que la API aceptó la emisión (ISO 8601 con zona horaria). | | `fh_autorizacion` | `str \| None` | Momento de la autorización del SRI, cuando existe. No la uses para decidir; decide con `estado`. | | `es_final`, `es_autorizado` | `bool` | Propiedades calculadas, descritas en [Estados tipados](#estados-tipados). | ## Estados tipados `Operation`, `Admission` y `Comprobante` conservan los campos de la API (`estado`, `cod_estado`, `tipo_documento`) y agregan propiedades tipadas. Un valor que el SDK no reconoce no rompe tu código, porque se lee como `DESCONOCIDO`, o como `None` en `tipo_comprobante`, y el texto original sigue en el campo `str`. Los enums heredan de `str`, así que `EstadoOperacion.AUTORIZADO == "autorizado"`. | Propiedad | Tipo | Valores | |---|---|---| | `Operation.estado_operacion`, `Comprobante.estado_operacion` | `EstadoOperacion` | `RECIBIDO`, `AUTORIZADO`, `RECHAZADO`, `RECHAZO_CONFIGURACION`, `ERROR`, `CANCELADO`, `DESCONOCIDO` | | `Operation.tipo_comprobante`, `Comprobante.tipo_comprobante` | `TipoComprobante \| None` | `FACTURA` (`01`), `LIQUIDACION_COMPRA` (`03`), `NOTA_CREDITO` (`04`), `NOTA_DEBITO` (`05`), `GUIA_REMISION` (`06`), `RETENCION` (`07`); `None` si el código no se conoce | | `Operation.es_final`, `Comprobante.es_final` | `bool` | `True` si `estado` es cualquier valor distinto de `recibido`. | | `Operation.es_autorizado`, `Comprobante.es_autorizado` | `bool` | `True` si `estado` es `autorizado`. | | `WebhookEvent.event_type` | `TipoEventoWebhook` | `DOCUMENTO_AUTORIZADO`, `DOCUMENTO_RECHAZADO`, `DOCUMENTO_FALLIDO`, `OPERACION_REQUIERE_ATENCION`, `DESCONOCIDO` | Los valores de `codEstado` están como constantes `int` en la clase `CodEstado`, con el nombre de cada código del [catálogo](/v1/guias/errores#catalogo-de-codestado) en mayúsculas, por ejemplo `CodEstado.RECHAZO_SRI` (3001), `CodEstado.COMPROBANTE_INVALIDO` (3002) o `CodEstado.LIMITE_SOLICITUDES` (5005). `estado_de_cod_estado(codigo)` devuelve el `EstadoOperacion` que corresponde al primer dígito, incluso para un código que tu versión del SDK todavía no conoce. ```python import os from ecuafact import CodEstado, EcuafactClient, EcuafactClientOptions, EstadoOperacion with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: operacion = client.get_operacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f") if operacion.estado_operacion is EstadoOperacion.AUTORIZADO: print("Descarga el RIDE") elif operacion.estado_operacion is EstadoOperacion.RECIBIDO: print("Consulta mas tarde") elif operacion.cod_estado == CodEstado.RECHAZO_SRI: print("Corrige y emite un comprobante nuevo:", operacion.errores) else: print("Revisa el resultado:", operacion.cod_estado, operacion.msg_error, operacion.errores) ``` Qué hacer ante cada `estado` y cada `codEstado` se explica en [Qué hacer según el estado](/v1/guias/consulta-operacion#que-hacer-segun-el-estado). ## Webhooks Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle y, antes de procesar cada entrega, comprobar que te la enviamos nosotros. El SDK te ayuda a recibir webhooks: verifica la firma y te entrega el evento tipado, pero no administra los destinos. Los destinos (la URL a la que enviamos cada evento, sus eventos suscritos y su secreto) los administras desde el Portal del Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP o con la API REST, como se explica en [Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api). `construir_evento` verifica la cabecera `Ecuafact-Signature` (`t=,v1=`) contra el cuerpo **crudo** y, si es válida, devuelve el evento tipado (`WebhookEvent`). Si algo falla, lanza `EcuafactWebhookException` y su atributo `motivo` te dice qué responder: | `motivo` | Cuándo | Responde | |---|---|---| | `"firma_invalida"` (`EcuafactWebhookException.FIRMA_INVALIDA`) | La cabecera falta o está malformada, la firma no coincide con ningún secreto o está fuera de la tolerancia (300 s por defecto, en ambos sentidos). | 401 | | `"cuerpo_invalido"` (`EcuafactWebhookException.CUERPO_INVALIDO`) | La firma es válida, pero el cuerpo no es JSON o no es un objeto JSON. | 400 | La firma se verifica primero: un cuerpo no JSON con firma inválida llega con `motivo` `"firma_invalida"`, y `es_firma_invalida` es `True` en ese caso. La firma del método es `construir_evento(secretos, cabecera, cuerpo, tolerance_seconds=300, now=None)`, y `WebhookEvent.construir(...)` hace lo mismo. Acepta un secreto o una lista de secretos (`str` o `bytes`), y la entrega es válida si coincide con cualquiera; así puedes rotar el secreto sin rechazar entregas. Agrega el nuevo, publica tu aplicación y quita el anterior cuando las entregas lleguen firmadas con el nuevo, como se explica en [Rotación de secreto](/v1/guias/webhooks-firma#rotacion-de-secreto). El ejemplo siguiente usa Flask, que instalas con `pip install flask`. Guarda tu secreto en `ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en `ECUAFACT_WEBHOOK_SECRET_ANTERIOR`. ```python # Guarda como webhook.py. Instala: pip install ecuafact flask. Ejecuta: python webhook.py import os from flask import Flask, request from ecuafact import EcuafactWebhookException, TipoEventoWebhook, construir_evento app = Flask(__name__) SECRETOS = [s for s in (os.environ.get("ECUAFACT_WEBHOOK_SECRET"), os.environ.get("ECUAFACT_WEBHOOK_SECRET_ANTERIOR")) if s] procesados = set() # en produccion, una tabla con clave unica @app.post("/webhooks/ecuafact") def webhook_ecuafact(): cuerpo_crudo = request.get_data() # bytes, tal como llegaron cabecera = request.headers.get("Ecuafact-Signature", "") try: evento = construir_evento(SECRETOS, cabecera, cuerpo_crudo) except EcuafactWebhookException as error: return "", (401 if error.es_firma_invalida else 400) clave = (evento.event_type_raw, evento.resource_id) if clave in procesados: return "", 200 # reintento o reenvio del mismo evento: no lo proceses de nuevo procesados.add(clave) if evento.event_type is TipoEventoWebhook.DOCUMENTO_AUTORIZADO: print("Autorizado", evento.id_operacion, evento.clave_acceso) elif evento.event_type is TipoEventoWebhook.DOCUMENTO_RECHAZADO: print("Rechazo fiscal", evento.id_operacion, evento.cod_estado, evento.errores) elif evento.event_type is TipoEventoWebhook.DOCUMENTO_FALLIDO: print("No emitido", evento.id_operacion, evento.estado, evento.cod_estado) else: print("Evento", evento.event_type_raw, "prueba =", evento.probe) return "", 200 if __name__ == "__main__": app.run(port=3000) ``` Responde con un 2xx en menos de 15 segundos. Si el procesamiento tarda, guarda el evento, responde 200 y procésalo después. Ten en cuenta que no reintentamos una entrega que respondiste con un 4xx, como el 401 por firma inválida o el 400 por cuerpo inválido. | Atributo de `WebhookEvent` | Tipo | Descripción | |---|---|---| | `event_type` | `TipoEventoWebhook` | Tipo tipado; `DESCONOCIDO` si el SDK no reconoce el valor. | | `event_type_raw` | `str \| None` | Valor original de `eventType` (`document.authorized`, `document.rejected`, `document.failed`, `operation.requires_attention`). | | `resource_id` | `str \| None` | En los eventos `document.*` es el `idOperacion`. Úsalo con `event_type_raw` para deduplicar. | | `occurred_at_utc` | `datetime \| None` | Momento del evento, con zona UTC. | | `id_operacion` | `str \| None` | Operación que devolvió la emisión. | | `estado` | `str \| None` | El mismo `estado` del seguimiento: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`. | | `tipo_documento` | `str \| None` | Tipo de comprobante (`01` a `07`), cuando el evento lo trae. | | `clave_acceso` | `str \| None` | Clave de acceso; puede faltar en `document.failed`. | | `cod_estado` | `int \| None` | Código numérico del resultado, por ejemplo 2001 en `document.authorized`, 3001 (`rechazo_sri`) en `document.rejected` o 4002 (`firma_no_valida`) en `document.failed`. Decide con `estado` y `cod_estado`, no solo con el tipo del evento. | | `msg_error` | `str \| None` | Descripción fija del código; `None` cuando no hay error. | | `errores` | `tuple[str, ...]` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacío si no hay detalle. | | `fh_autorizacion` | `str \| None` | Momento de la autorización del SRI, cuando existe. | | `probe` | `bool` | `True` en el evento de prueba del portal. | | `cuerpo` | `Mapping` | El cuerpo completo, incluidos campos que el SDK no mapea. | Si solo necesitas saber si la firma es válida, usa `verify(secret, header, body, now=None, tolerance_seconds=300)`, que devuelve `bool` y nunca lanza una excepción. Acepta un secreto o una lista, y el cuerpo como `str`, `bytes`, `bytearray` o `memoryview`. Para pruebas automatizadas, `sign(secret, unix_seconds, body)` genera una cabecera `Ecuafact-Signature` válida. ### Standard Webhooks Cada entrega trae además las cabeceras del estándar [Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks) (`webhook-id`, `webhook-timestamp` y `webhook-signature`), que corresponden a la misma firma. Con el SDK puedes verificar cualquiera de las dos, sin decidir cuál llegó. | Función | Qué hace | |---|---| | `verificar_webhook(secret, cabeceras, cuerpo, now=None, tolerance_seconds=300)` | Devuelve `bool`. Acepta la firma de `Ecuafact-Signature` o la de Standard Webhooks, según las cabeceras de la petición. Los nombres de las cabeceras no distinguen mayúsculas. Nunca lanza una excepción. | | `construir_evento_webhook(secretos, cabeceras, cuerpo, tolerance_seconds=300, now=None)` | Igual que `construir_evento`, pero verifica cualquiera de las dos firmas. Lanza `EcuafactWebhookException` con los mismos `motivo`. `WebhookEvent.construir_desde_cabeceras(...)` hace lo mismo. | | `verificar_estandar(secret, webhook_id, webhook_timestamp, webhook_signature, cuerpo, now=None, tolerance_seconds=300)` | Devuelve `bool`. Verifica solo la firma de Standard Webhooks. | | `firmar_estandar(secreto, webhook_id, unix_seconds, cuerpo)` | Devuelve el valor de `webhook-signature` (`v1,`). Sirve para pruebas automatizadas. | El secreto puede llevar o no el prefijo `whsec_`, y también aceptas una lista de secretos para la rotación. En Flask, `request.headers` sirve como `cabeceras`. ```python evento = construir_evento_webhook(SECRETOS, request.headers, request.get_data()) ``` > [!WARNING] > Verifica la firma sobre el cuerpo crudo, que obtienes con `request.get_data()` > en Flask o con `await request.body()` en FastAPI. Si usas `request.json` y vuelves a > serializar, la firma no coincide. Los eventos, los reintentos de entrega y la deduplicación están en [Webhooks](/v1/guias/webhooks), y el algoritmo de la firma, en [Verificación de firma](/v1/guias/webhooks-firma). ## Errores Todas las excepciones del SDK heredan de `EcuafactSdkException`, y las que vienen de una respuesta de la API heredan además de `EcuafactApiException`. Captura primero las específicas y al final las generales. Todas se importan de `ecuafact`. | Excepción | Hereda de | Cuándo ocurre | Qué hacer | |---|---|---|---| | `EcuafactConfigurationException` | `EcuafactSdkException` | Las opciones del cliente o de `RequestOptions` no son válidas, como se explica en [Configuración](#configuracion). | Corrige la configuración. No llama a la API. | | `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API, o la respuesta se cortó al leerla, tras agotar los intentos. | Reintenta más tarde con la misma `idempotency_key`. `es_reintentable` es `True`. | | `EcuafactTimeoutException` | `EcuafactSdkException` | Se agotó `timeout` en el último intento o `total_timeout` de la llamada. | Si emitías, consulta el seguimiento o reintenta con la misma `idempotency_key`. `es_reintentable` es `True`. | | `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida (`motivo` `"firma_invalida"`), o cuerpo que no es un objeto JSON (`motivo` `"cuerpo_invalido"`). | Responde 401 si `motivo` es `"firma_invalida"` y 400 si es `"cuerpo_invalido"`. No proceses el evento. | | `EcuafactAuthException` | `EcuafactApiException` | HTTP 401 o 403, con el `codEstado` 3009 (`credenciales_invalidas`), 3010 (`ip_no_autorizada`) o 3011 (`acceso_denegado`). | Corrige la API Key, registra la IP o revisa que el contribuyente y el tipo estén habilitados. | | `EcuafactValidationException` | `EcuafactApiException` | HTTP 400 o 422, con el `codEstado` 3002 (`comprobante_invalido`), 3003 (`solicitud_invalida`), 3007 (`version_no_soportada`) o 3012 (`filtros_invalidos`). | Corrige según `errores`. Un 422 con el `codEstado` 3002 consume 1 documento como intento. | | `EcuafactNotFoundException` | `EcuafactApiException` | HTTP 404, con el `codEstado` 3013 (`no_encontrado`), o con `cod_estado` en `None` si la ruta no existe y la respuesta no trae cuerpo de error. | Verifica el `id_operacion` o la `clave_acceso`, y que llamas a la URL del ambiente donde emitiste. | | `EcuafactConflictException` | `EcuafactApiException` | HTTP 409, con el `codEstado` 3004 (`comprobante_duplicado`), 3005 (`conflicto_idempotencia`) o 3014 (`correo_no_disponible`). | Mira el `cod_estado` en la tabla de códigos de abajo. | | `EcuafactRateLimitException` | `EcuafactApiException` | HTTP 429 con un `codEstado` distinto de 4004, normalmente 5005 (`limite_solicitudes`). | Espera `retry_after` y reintenta con la misma `idempotency_key`. El SDK ya lo reintenta por defecto, así que la excepción llega cuando se agotan los intentos o si desactivaste `retry_rate_limited`. | | `EcuafactQuotaException` | `EcuafactApiException` | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`): cupo agotado. | Amplía el cupo ([`GET /v1/consumo`](/v1/guias/consumo)). No reintentes. | | `EcuafactServerException` | `EcuafactApiException` | HTTP 5xx, con el `codEstado` 5001 (`error_interno`), 5002 (`servicio_no_disponible`), 5003 (`error_dependencia`) o 5004 (`tiempo_agotado`), tras agotar los intentos si el estado es reintentable. | Si `es_reintentable` es `True`, reintenta más tarde con la misma `idempotency_key`. Un 501 no se reintenta. | | `EcuafactApiException` | `EcuafactSdkException` | Cualquier otro estado de error de la API, por ejemplo 413 con el `codEstado` 3006 (`cuerpo_excedido`). | Revisa `cod_estado`, `msg_error` y `errores`. | | `EcuafactTipoComprobanteException` | `EcuafactSdkException` | El objeto que pasas a `emitir`/`validar` no es uno de los seis modelos de solicitud, o el filtro `tipo_documento` de `listar_operaciones` no es un tipo conocido. | Usa el modelo de su tipo, como se explica en [Tipo de comprobante](#tipo-de-comprobante). No llama a la API. | | `EcuafactResponseTooLargeException` | `EcuafactSdkException` | El cuerpo de la respuesta supera el tope `max_response_bytes`. Trae `limite` y `bytes_leidos`. | Sube el tope o desactívalo si esperas archivos más grandes. No se reintenta. | | `EcuafactSdkException` | `Exception` | Otros errores locales: `Idempotency-Key` inválida, `id_operacion` que no es UUID, falta el contribuyente por defecto, `identificacion` que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, `.` o `..`, argumentos vacíos, o una respuesta 2xx vacía o ilegible. | Corrige la llamada. Si ocurre al emitir, repite la emisión con la `idempotency_key` de la excepción, como se explica en [Idempotencia y reintentos](#idempotencia-y-reintentos). | | Atributo de `EcuafactApiException` | Tipo | Descripción | |---|---|---| | `cod_estado` | `int \| None` | Código numérico del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), por ejemplo 3002 o 3004. Úsalo para decidir, comparándolo con las constantes de `CodEstado`. `None` si la respuesta no trae cuerpo de error. | | `estado` | `str \| None` | `estado` de la respuesta de error, como `rechazado`, `rechazo_configuracion` o `error`; si no llegó, el que indica el primer dígito de `cod_estado`. | | `msg_error` | `str \| None` | Descripción general y fija del código. Muéstrala o regístrala, pero no la uses para decidir. | | `estado_http` | `int` | Estado HTTP. | | `errores` | `list[str]` | Detalle específico del error, como la ruta del campo que falla en un 3002. Lista vacía cuando no hay detalle. | | `correlation_id` | `str \| None` | Cabecera `X-Correlation-Id`. Inclúyelo al pedir soporte. | | `idempotency_key` | `str \| None` | Clave usada en la emisión; reutilízala al reintentar. | | `advertencias` | `list[str]` | Avisos que acompañan al error, por ejemplo en el 422 de la validación. Lista vacía cuando no hay. | | `retry_after` | `datetime.timedelta \| None` | Espera indicada por la cabecera `Retry-After`; `None` si no llegó. | | `es_reintentable` | `bool` | `True` si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el `codEstado` 5005. El 429 con 4004 (cupo agotado) no es reintentable. | `correlation_id`, `idempotency_key` y `es_reintentable` también existen en `EcuafactConnectionException` y `EcuafactTimeoutException`. ```python import os import json import time from ecuafact import ( EcuafactApiException, EcuafactClient, EcuafactClientOptions, EcuafactConnectionException, EcuafactQuotaException, EcuafactRateLimitException, EcuafactTimeoutException, EcuafactValidationException, FacturaRequest, ) with open("comprobante.json", encoding="utf-8") as archivo: comprobante = FacturaRequest.model_validate(json.load(archivo)) with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: try: r = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001") print(r.admission.estado, r.admission.id_operacion) except EcuafactValidationException as error: # Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual. for detalle in error.errores: print(detalle) except EcuafactQuotaException: print("Cupo agotado: compra un paquete. No reintentes.") except EcuafactRateLimitException as error: espera = error.retry_after.total_seconds() if error.retry_after else 1 print(f"Limite de solicitudes: espera {espera} s y reintenta con {error.idempotency_key}") time.sleep(espera) except EcuafactApiException as error: print(error.estado_http, error.cod_estado, error.msg_error, error.errores, "reintentable =", error.es_reintentable, "correlation =", error.correlation_id) except (EcuafactConnectionException, EcuafactTimeoutException) as error: # Sin conexion o sin respuesta: reintenta mas tarde con la MISMA Idempotency-Key. print(error, "clave =", error.idempotency_key) ``` Estos son los códigos que verás con más frecuencia. El catálogo completo, con el nombre de cada código, está en [Errores](/v1/guias/errores#catalogo-de-codestado), y las constantes de `CodEstado` llevan ese mismo nombre, escrito con la convención del lenguaje. | `codEstado` | Nombre | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---|---| | 3009 | `credenciales_invalidas` | 401 | API Key ausente o inválida. | Corrige la API Key. No reintentes sin cambiar nada. | | 3010 | `ip_no_autorizada` | 403 | La IP no está permitida o no se pudo identificar. | Registra tu IP en **Cuenta > IP permitidas** o llama directo a la URL de la API, sin proxies intermedios; si persiste, contacta a soporte con el `correlation_id`. | | 3011 | `acceso_denegado` | 403 | Contribuyente, tipo de comprobante no habilitado, o `infoTributaria.ruc` no coincide con el contribuyente de la ruta. | Revisa `get_contexto()` (`puede_emitir`, `tipos_comprobante`). | | 5005 | `limite_solicitudes` | 429 | Superaste el límite de solicitudes por minuto. | Espera `retry_after` y reintenta con la misma `Idempotency-Key`, aunque el SDK ya lo hace por defecto; reduce el ritmo. | | 3003 | `solicitud_invalida` | 400 | Cabeceras inválidas (por ejemplo, `Idempotency-Key`) o JSON mal formado. | Corrige según `errores`. | | 3002 | `comprobante_invalido` | 422 | Campos del comprobante faltantes o mal formados, campos desconocidos o de otro tipo, o una regla fiscal incumplida (totales, impuestos). | Corrige según `errores`; consume 1 documento como intento, sin usar un número de la serie. | | 3012 | `filtros_invalidos` | 400 | Filtro de consulta fuera de rango (fechas o `max`). | Ajusta los filtros a los [límites](/v1/guias/limites). | | 3006 | `cuerpo_excedido` | 413 | Cuerpo mayor a 2 MiB en la emisión (1 MiB en otros `POST`/`PUT`). | Reduce el comprobante. | | 3004 | `comprobante_duplicado` | 409 | Ya existe un comprobante con ese número recibido, autorizado o rechazado por el SRI. | No reenvíes; si querías otro comprobante, usa otro `secuencial` u omítelo para que se asigne el siguiente. | | 3005 | `conflicto_idempotencia` | 409 | Misma `Idempotency-Key` o `referenciaExterna` con otro contenido. | Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. | | 4004 | `cupo_agotado` | 429 | Se agotó el cupo de documentos. El SDK no lo reintenta. | Revisa `get_consumo()`; compra un paquete. | | 3013 | `no_encontrado` | 404 | Operación, comprobante o RIDE no encontrado. | Verifica el id o la clave; el RIDE existe solo si está autorizado. | | 5001, 5002, 5003, 5004 | `error_interno`, `servicio_no_disponible`, `error_dependencia`, `tiempo_agotado` | 500, 503, 502, 504 | Error interno, servicio no disponible, o el servicio de validación fiscal falló o no respondió. | El SDK ya reintentó; vuelve a intentar más tarde con la misma `Idempotency-Key`. | ## Idempotencia y reintentos La `Idempotency-Key` evita emitir dos veces el mismo comprobante si una llamada se repite, por ejemplo después de un timeout o de una caída de la red. - Si no la pasas, o pasas `None`, el SDK genera un UUID sin guiones, lo usa en todos sus reintentos y te lo devuelve en `resultado.idempotency_key` o, si falla, en `error.idempotency_key`, que exponen todas las excepciones del SDK. - Te recomendamos pasar un valor estable por intención, como tu número interno de factura, o un UUID v4 que guardes junto al documento. - El SDK valida la clave antes de enviarla con la misma regla de la API: de 1 a 128 caracteres, solo letras, dígitos y `-` `_` `.` `:` `/`. Si no cumple, incluida la cadena vacía, lanza `EcuafactSdkException` sin llamar a la API. - `get_operacion`, `consultar_operacion` y `esperar_resultado` exigen un UUID; si no lo es, lanzan `EcuafactSdkException` sin llamar a la API. > [!WARNING] > Si reintentas una emisión desde tu aplicación, reutiliza la misma > `Idempotency-Key`. Una clave nueva para el mismo comprobante puede duplicar la > emisión. Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción (`EcuafactSdkException`) conserva la `Idempotency-Key` en `idempotency_key`; repite la emisión con esa misma clave y no se duplica el comprobante. Si necesitas ubicar la llamada en tus registros, envía tu propio `correlation_id` con `RequestOptions`. | Situación | Se reintenta | Detalle | |---|---|---| | HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con `retry_status_codes`. Solo en `GET`, en `POST`/`PUT` con `Idempotency-Key` (la emisión siempre la lleva), en la validación sin emitir y en el cambio de logo. | | HTTP 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí, salvo con `retry_rate_limited=False` | Espera lo que indica `Retry-After` y reintenta. Con `retry_rate_limited=False` lanza `EcuafactRateLimitException` con `retry_after`, y decides tú cuándo reintentar. | | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`) | Nunca | Esperar no repone el cupo. Lanza `EcuafactQuotaException`. | | Error de red o timeout de un intento | Sí | Se reintenta en las mismas condiciones; al agotar los intentos lanza `EcuafactConnectionException` o `EcuafactTimeoutException`. | | Descarga de RIDE/XML y cambio de logo | Sí | Se reintentan ante un estado HTTP transitorio o un error de red. El cambio de logo no lleva `Idempotency-Key`, pero lo reintentamos porque subir el mismo archivo otra vez deja el perfil igual. | | Validación sin emitir (`validar`, `validar_en`) | Sí | Se reintenta como una consulta ante un estado HTTP transitorio o un error de red. No lleva `Idempotency-Key` porque no emite nada. | | `actualizar_perfil` | No | No lleva `Idempotency-Key`, así que un reintento automático podría repetir el efecto. Sus errores llegan con la misma jerarquía de excepciones y con `correlation_id`. | | Cualquier otro 4xx | No | Se lanza la excepción de inmediato. | Después del intento `n`, el SDK espera según esta tabla. | `retry_backoff` | Espera calculada | Con los valores por defecto | |---|---|---| | `linear` | `retry_base_delay_ms` x `n` + aleatorio entre 0 y `retry_jitter_ms` x `n` | 200 ms (+ hasta 50) y 400 ms (+ hasta 100) | | `exponential` | `retry_base_delay_ms` x 2^(`n`-1) + aleatorio entre 0 y `retry_jitter_ms` | 200 ms y 400 ms (+ hasta 50 cada una) | Si la respuesta trae un `Retry-After` mayor que la espera calculada y `respect_retry_after` es `True`, espera ese tiempo. La espera nunca supera `max_retry_delay_ms`. Con `total_timeout`, el SDK no inicia una espera que terminaría después del tope, sino que lanza el error del último intento; y si el tope se agota antes de un intento, lanza `EcuafactTimeoutException`. ## Opciones por llamada Puedes cambiar el tiempo máximo, el tope total, la correlación, la información adicional o los reintentos de una sola llamada sin tocar la configuración del cliente. Cada método que llama a la API acepta `opciones=RequestOptions(...)` como último argumento, siempre por nombre. Lo que no indiques usa la configuración del cliente. | Campo | Valor por defecto | Qué hace | |---|---|---| | `timeout` | `None` (usa `options.timeout`) | Tiempo máximo de cada intento, en segundos o como `httpx.Timeout`. Mayor que 0. | | `total_timeout` | `None` (usa `options.total_timeout`) | Tope de toda la llamada, incluidos reintentos y esperas, en segundos. Mayor que 0. | | `correlation_id` | `None` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres `A-Z a-z 0-9 . _ -`. | | `additional_info` | `None` (usa `options.additional_info`) | Se envía en la cabecera `X-Additional-Info` y reemplaza el valor del cliente solo en esta llamada. Con `None` usa el del cliente, y con `""` no envía la cabecera en esta llamada. Sigue el mismo formato que en el cliente, descrito en [Información adicional](#informacion-adicional). | | `validar_antes_de_emitir` | `None` | Solo en `emitir` y `emitir_en`. `True` o `False` reemplaza el valor del cliente en esta llamada; `None` usa el del cliente. | | `reintentos` | `True` | `False` desactiva los reintentos solo en esta llamada. `True` no reactiva reintentos que el cliente desactivó (`retry_transient_failures=False`) ni reintenta solicitudes sin `Idempotency-Key` (`actualizar_perfil`). | El SDK Python no tiene cancelación, así que acota la llamada con `timeout` y `total_timeout`. En `esperar_resultado`, las opciones se aplican a cada consulta. La API usa y devuelve la correlación que enviaste. La encuentras en `resultado.correlation_id` de la emisión y en `correlation_id` de cualquier excepción del SDK, incluidas `EcuafactTimeoutException` y `EcuafactConnectionException`. Si la API no devuelve `X-Correlation-Id`, se expone la que enviaste. ```python # Guarda como opciones.py. Instala: pip install ecuafact. Ejecuta: python opciones.py import os from ecuafact import EcuafactClient, EcuafactClientOptions, RequestOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: # Un solo intento y correlacion propia para esta consulta. contexto = client.get_contexto( opciones=RequestOptions(reintentos=False, correlation_id="pedido-2026-0457") ) print("Contribuyentes:", len(contexto.contribuyentes)) # Mas tiempo para una descarga grande, con tope total de 2 minutos. ride = client.descargar_ride( "0123456789001", "0710202601012345678900110010010000001231234567811", opciones=RequestOptions(timeout=60, total_timeout=120), ) with open("ride.pdf", "wb") as archivo: archivo.write(ride.contenido) ``` Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu emisor. Un `correlation_id` con espacios o de más de 64 caracteres, o un tiempo menor o igual a 0, lanza `EcuafactConfigurationException` al crear `RequestOptions`, sin llamar a la API. ## Información adicional Puedes enviar un dato tuyo en cada solicitud, por ejemplo la versión de tu ERP o la sucursal que emite, para que ubiquemos tus llamadas cuando nos pidas soporte. Viaja en la cabecera `X-Additional-Info`; la API la asocia a tu solicitud y no cambia su respuesta. Es la única cabecera personalizada que admite el SDK. Las reglas de la API están en [Límites](/v1/guias/limites#cabeceras). | Dónde | Qué hace | |---|---| | `EcuafactClientOptions.additional_info` | Se envía en todas las solicitudes del cliente, incluidas las consultas de `esperar_resultado`, los reintentos y las llamadas desde `client.para(...)`. Con `None` o `""` no se envía. | | `RequestOptions.additional_info` | Reemplaza el valor del cliente solo en esa llamada. Con `None` usa el del cliente, y con `""` no envía la cabecera en esa llamada. | El SDK valida el valor en tu proceso, antes de llamar a la API, con estas reglas: - Solo caracteres ASCII imprimibles (0x20 a 0x7E): sin tildes, `ñ` ni saltos de línea. - Sin espacios al inicio ni al final. - Máximo 256 caracteres. Si no cumple, el SDK lanza `EcuafactConfigurationException` al crear el cliente o `RequestOptions`, sin llamar a la API. El valor no aparece en `repr` ni en los mensajes de excepción. No pongas en él la API Key ni datos personales. ```python # Guarda como info_adicional.py. Instala: pip install ecuafact. Ejecuta: python info_adicional.py import os from ecuafact import EcuafactClient, EcuafactClientOptions, RequestOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], additional_info="erp=mi-erp; version=4.2", # en todas las solicitudes )) as client: client.get_contexto() # X-Additional-Info: erp=mi-erp; version=4.2 # Solo en esta llamada: client.get_consumo(opciones=RequestOptions(additional_info="erp=mi-erp; lote=2026-10-08")) ``` | Error | Por qué pasa | Qué hacer | |---|---|---| | `EcuafactConfigurationException` al crear el cliente | `additional_info` tiene tildes, `ñ`, saltos de línea u otro carácter fuera de 0x20 a 0x7E, espacios al inicio o al final, o más de 256 caracteres. | Corrige el valor: quita tildes y espacios de los extremos y acórtalo. | | `EcuafactConfigurationException` al crear `RequestOptions` | El mismo problema en `RequestOptions.additional_info`. No se llamó a la API. | Corrige el valor de esa llamada. | ## Conexión: proxy, TLS y cliente propio Puedes configurar la conexión según lo que necesites; la tabla muestra qué opción usar en cada caso. Si no configuras nada, el SDK crea y cierra su propio `httpx.Client`. | Necesitas | Usa | Detalle | |---|---|---| | Proxy, CA corporativa o tiempo de conexión | `proxy`, `verify`, `connect_timeout` | El SDK los aplica a su cliente interno. | | Control total del pool, la autenticación del proxy, los certificados de cliente o los eventos de `httpx` | `http_client=httpx.Client(...)` | El SDK usa tu cliente y **no** lo cierra, así que ciérralo tú. No lo combines con `proxy`, `verify` ni `transport`. | | Pruebas sin red | `transport=httpx.MockTransport(...)` | Responde con lo que defina tu función. | Este ejemplo configura un proxy y una CA propia, y ajusta los reintentos. ```python import os from ecuafact import EcuafactClient, EcuafactClientOptions, RetryBackoff opciones = EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], retry_backoff=RetryBackoff.EXPONENTIAL, retry_base_delay_ms=500, retry_rate_limited=True, total_timeout=60, proxy="http://proxy.miempresa.local:8080", verify="/etc/ssl/certs/ca-miempresa.pem", connect_timeout=5, ) with EcuafactClient(opciones) as client: print(len(client.get_contexto().contribuyentes)) ``` Y este otro usa tu propio cliente `httpx`. ```python import os import httpx from ecuafact import EcuafactClient, EcuafactClientOptions with httpx.Client( proxy="http://proxy.miempresa.local:8080", verify="/etc/ssl/certs/ca-miempresa.pem", limits=httpx.Limits(max_connections=20), ) as http: with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], http_client=http, )) as client: print(len(client.get_contexto().contribuyentes)) ``` El tiempo de cada intento sigue siendo el `timeout` y el `connect_timeout` del SDK, también con un cliente propio, porque el SDK los pasa en cada solicitud. ## Constructores de comprobantes Puedes armar la [Estructura del comprobante](/v1/guias/emision) con métodos en lugar de escribir el JSON. `ComprobanteBuilder` es opcional y solo ayuda a armar el cuerpo: produce el modelo de solicitud de su tipo (`FacturaRequest`, `LiquidacionCompraRequest`, `NotaCreditoRequest`, `NotaDebitoRequest`, `GuiaRemisionRequest` o `RetencionRequest`) que armas a mano, sin calcular, sin completar valores y sin lanzar por reglas de negocio. Los campos requeridos, los formatos, los catálogos, los topes y los importes los valida únicamente la API; para comprobarlos usa [`validar_en`](#validar-sin-emitir) o [`validar_antes_de_emitir`](#validar-antes-de-emitir-opcional). Todo valor que asignes se envía tal cual. ```python # Guarda como constructor.py. Instala: pip install ecuafact. Ejecuta: python constructor.py import datetime import os from ecuafact import ( ComprobanteBuilder, EcuafactClient, EcuafactClientOptions, RequestOptions, ) hoy = (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(hours=5)).date() # Ecuador # Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor. factura = ( ComprobanteBuilder.factura("0123456789001", "001", "001") .referencias("MiERP", "FACTURA-2026-0002") .fecha_emision(hoy) .comprador("07", "9999999999999", "CONSUMIDOR FINAL") .linea("SERV-001", "Servicio de prueba", 1, "10.00", 0, ("4", 15)) .pago("01", "11.50") ) comprobante = factura.construir() with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: r = client.emitir_en( "0123456789001", comprobante, "FACTURA-2026-0002", opciones=RequestOptions(correlation_id="pedido-2026-0458"), ) validacion = client.validar_en("0123456789001", comprobante) # la API decide print(validacion.valido, validacion.errores, validacion.advertencias) print(r.admission.estado, r.admission.id_operacion, r.correlation_id) ``` Si la API acepta el comprobante, deberías ver `True [] []` y luego `recibido pedido-2026-0458`. Si ejecutas el script otro día con la misma `Idempotency-Key`, la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`); en ese caso usa una `Idempotency-Key` y una `referenciaExterna` nuevas. El ejemplo siguiente arma una nota de crédito por el total de la factura `001-001-000000123`, con un comprador con cédula; las líneas de la nota de crédito usan `codigoInterno`. Cambia el número y la fecha por los de una factura autorizada de tu emisor. ```python import datetime from ecuafact import ComprobanteBuilder hoy = (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(hours=5)).date() nota = ( ComprobanteBuilder.nota_credito("0123456789001", "001", "001") .referencias("MiERP", "NC-2026-0001") .fecha_emision(hoy) .comprador("05", "0123456789", "CLIENTE DE PRUEBA") .documento_modificado("01", "001-001-000000123", "01/10/2026", "11.50") .motivo("Devolucion del servicio") .linea("SERV-001", "Servicio de prueba", 1, "10.00", 0, ("4", 15)) .info(valor_modificacion="11.50") ) print(nota.construir().info.valor_modificacion) # 11.50 ``` La emites igual que la factura, con `client.emitir_en(...)` y su propia `Idempotency-Key`. Las reglas de este tipo están en [Nota de crédito](/v1/guias/emision-04). | Tipo | Entrada | Métodos propios | |---|---|---| | Factura (`01`) | `ComprobanteBuilder.factura(ruc, estab, pto_emi)` | `comprador(tipo_identificacion, identificacion, razon_social, direccion=None, *, correo, telefono)`, `linea`, `detalle`, `propina`, `moneda`, `pago` | | Liquidación de compra (`03`) | `ComprobanteBuilder.liquidacion_compra(...)` | `proveedor(...)`, `linea`, `detalle`, `moneda`, `pago` | | Nota de crédito (`04`) | `ComprobanteBuilder.nota_credito(...)` | `comprador`, `documento_modificado(cod_doc_modificado, numero, fecha_emision, total=None)`, `motivo(motivo)`, `linea`, `detalle`, `moneda` | | Nota de débito (`05`) | `ComprobanteBuilder.nota_debito(...)` | `comprador`, `documento_modificado(cod_doc_modificado, numero, fecha_emision)`, `motivo(razon, valor)`, `iva(tarifa)`, `moneda`, `pago` | | Guía de remisión (`06`) | `ComprobanteBuilder.guia_remision(...)` | `transportista(tipo_identificacion, identificacion, razon_social, placa)`, `traslado(dir_partida, fecha_inicio, fecha_fin)`, `destinatario(identificacion, razon_social, direccion, motivo_traslado, *, cod_estab_destino, ruta, doc_aduanero_unico)`, `linea(codigo, descripcion, cantidad)` | | Retención (`07`) | `ComprobanteBuilder.retencion(...)` | `sujeto_retenido`, `periodo_fiscal` (`MM/yyyy` o fecha), `parte_relacionada` (`True`/`False` o `SI`/`NO`), `documento_sustento`, `impuesto_sustento`, `retencion(codigo, codigo_retencion, base_imponible, porcentaje, valor=None)`, `pago` | Todos los constructores tienen además `referencias(origen, externa)`, `secuencial`, `fecha_emision`, `info(**campos)`, `info_adicional(nombre, valor)` y `construir()`, que devuelve una copia independiente. `fecha_emision` (todos menos la guía de remisión) acepta un texto `dd/MM/yyyy` o un `date`; la guía de remisión no la lleva, porque su fecha es la de `traslado`. El método `info` asigna campos de ese bloque por su nombre en `snake_case`. `linea(codigo, descripcion, cantidad, precio, descuento=0, iva=None, *, ice=None, codigo_auxiliar=None, precio_total_sin_impuesto=None, detalles_adicionales=None)` recibe `descuento` como un importe en dólares, no como un porcentaje. `iva` es opcional y se envía tal cual (`Tarifa`, la tupla `("4", 15)` o un `Impuesto`). El ICE de una línea va con `linea(..., ice=("3011", 10))`. Los importes que das como texto decimal (`"11.50"`) o como `Decimal` se envían como número JSON literal, sin pasar por `float`, para no perder precisión. ### Reglas de negocio solo en la API Las reglas de negocio de los comprobantes viven solo en la API, de modo que un cambio de regla no te obliga a actualizar el SDK. Por eso el SDK no calcula totales ni valida reglas fiscales, y los constructores tampoco validan; solo valida localmente lo que evita una petición mal construida: que la identificación tenga de 5 a 13 dígitos, que la `claveAcceso` y los demás datos de la ruta no estén vacíos, que los UUID sean válidos, el tipo de documento que elige la ruta, la `Idempotency-Key`, que `pagina` y `tamano_pagina` sean enteros, y la firma de los webhooks. Un importe que no es un número, como `"10,50"`, lanza `EcuafactSdkException` porque no se puede serializar sin perder precisión. ## Importes exactos Todos los importes, cantidades, precios y tarifas de la solicitud son `decimal.Decimal` (tipo `Importe`). En las respuestas de consulta, como el `total` de cada fila del listado de operaciones, el importe llega como `float`. Al crear un modelo (con su constructor o con `model_validate`) aceptan `Decimal`, `str`, `int` o `float`; un `float` se toma con 15 cifras significativas, así que `0.1 + 0.2` se envía como `0.3`. Si cambias un atributo después de crear el modelo, asigna un `Decimal`. El SDK envía cada `Decimal` como número JSON literal: `Decimal("11.50")` llega como `11.50`. `Pago.plazo` es un número, como en el contrato. Calcula con `Decimal` creado desde texto y redondea a 2 decimales. ```python import json from decimal import ROUND_HALF_UP, Decimal from ecuafact import FacturaRequest with open("comprobante.json", encoding="utf-8") as archivo: comprobante = FacturaRequest.model_validate(json.load(archivo)) base_imponible = Decimal("10.00") iva = (base_imponible * Decimal("0.15")).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) # 1.50 comprobante.info.total_sin_impuestos = base_imponible comprobante.info.importe_total = base_imponible + iva # 11.50 print(comprobante.info.importe_total) # 11.50 ``` Si tu código compara con `isinstance(x, float)` o mezcla `float` con `Decimal` en una operación, convierte el valor con `Decimal(str(x))` o `float(importe)`. Las reglas de cálculo de cada comprobante están en [Factura](/v1/guias/emision-01). ## Métodos La identificación que reciben los métodos es siempre el valor `identificacion` del contexto. Los modelos de respuesta exponen los campos en `snake_case` (`id_operacion`, `cod_estado`, `clave_acceso`). Todos los métodos que llaman a la API aceptan además `opciones=RequestOptions(...)` por nombre. La emisión y la validación toman la ruta del tipo del modelo que pasas (ver [Tipo de comprobante](#tipo-de-comprobante)); el cuerpo no lleva un campo de tipo. | Modelo | Documento | Ruta de emisión | Ruta de validación | |---|---|---|---| | `FacturaRequest` | Factura | `/v1/contribuyentes/{identificacion}/facturas` | `.../facturas/validar` | | `LiquidacionCompraRequest` | Liquidación de compra | `/v1/contribuyentes/{identificacion}/liquidaciones-compra` | `.../liquidaciones-compra/validar` | | `NotaCreditoRequest` | Nota de crédito | `/v1/contribuyentes/{identificacion}/notas-credito` | `.../notas-credito/validar` | | `NotaDebitoRequest` | Nota de débito | `/v1/contribuyentes/{identificacion}/notas-debito` | `.../notas-debito/validar` | | `GuiaRemisionRequest` | Guía de remisión | `/v1/contribuyentes/{identificacion}/guias-remision` | `.../guias-remision/validar` | | `RetencionRequest` | Comprobante de retención | `/v1/contribuyentes/{identificacion}/retenciones` | `.../retenciones/validar` | | Método | Endpoint | Devuelve | |---|---|---| | `get_contexto()` | `GET /v1/contexto` | `Contexto`, como se explica en [Contexto y consumo](#contexto-y-consumo) | | `emitir(comprobante, idempotency_key=None)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}` | `EmisionResultado` | | `emitir_en(identificacion, comprobante, idempotency_key=None)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` | | `validar(comprobante)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionResultado` | | `validar_en(identificacion, comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionResultado` (`valido`, `cod_estado`, `msg_error`, `errores`, `advertencias`, `correlation_id`), como se explica en [Validar sin emitir](#validar-sin-emitir). | | `listar_operaciones(*, identificacion=None, desde=None, hasta=None, tipo_documento=None, buscar=None, pagina=None, tamano_pagina=None)` | `GET /v1/operaciones` | `PaginaComprobantes` (ver [Listado de operaciones](#listado-de-operaciones)) | | `get_salud()` | `GET /salud` | `Salud` (`status` y `cuerpo`), como se explica en [Estado del servicio](#estado-del-servicio) | | `get_estado_servicio()` | `GET /estado` | `EstadoServicio` (`estado`, `medido_en`, `componentes`, `disponibilidad_90_dias`, `incidentes`). No envía API Key. Ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos). | | `listar_catalogos()` | `GET /v1/catalogos` | `IndiceCatalogos` (`catalogos`: lista de `ResumenCatalogo` con `nombre` y `descripcion`) | | `get_catalogo(nombre)` | `GET /v1/catalogos/{nombre}` | `DetalleCatalogo` (`nombre`, `descripcion`, `fuente`, `items`: lista de `ItemCatalogo`) | | `get_operacion(id_operacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation`. `id_operacion` es un UUID (`str` o `uuid.UUID`). | | `consultar_operacion(id_operacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias) | | `esperar_resultado(id_operacion, intervalo=5.0, maximo=120.0)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída. Los tiempos van en segundos, como se explica en [Seguimiento del resultado](#seguimiento-del-resultado). | | `descargar_ride(identificacion, clave_acceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | `ArchivoComprobante` (PDF) | | `descargar_xml(identificacion, clave_acceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | `ArchivoComprobante` (XML del comprobante autorizado) | | `get_consumo()` | `GET /v1/consumo` | `QuotaBucket`, como se explica en [Contexto y consumo](#contexto-y-consumo) | | `get_perfil(identificacion)` | `GET /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` | | `actualizar_perfil(identificacion, cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor`; `cambios` es un `PerfilEmisorUpdate` | | `actualizar_logo(identificacion, contenido, content_type, nombre_archivo)` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (ver [Logo del perfil](#logo-del-perfil)) | | `consultar_contribuyente(identificacion, fusionar=True, fuente=None)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta` | | `buscar_contribuyentes(apellidos, nombres=None, clase=None, max=None)` | `GET /v1/consultas/contribuyentes` | `list[BusquedaContribuyente]` | | `listar_establecimientos(ruc, filtro=None)` | `GET /v1/consultas/establecimientos/{ruc}` | `EstablecimientosContribuyente` | | `validar_identificacion(numero)` | `GET /v1/consultas/identificacion/validar/{numero}` | `ValidacionIdentificacion` (revisa `valido`) | | `decodificar_clave_acceso(clave_acceso)` | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | `ClaveAccesoDecodificada` | | `para(identificacion)` | - (no llama a la API) | `EcuafactContribuyente` | | `construir_evento(...)`, `verify(...)` y `sign(...)` | - (funciones exportadas, locales) | `WebhookEvent`, `bool` o `str` (ver [Webhooks](#webhooks)) | | `close()` | - | Cierra las conexiones del cliente interno. Lo hace solo si usas `with`. | Ten en cuenta además estos detalles de los métodos y de sus tipos: - `EmisionResultado` trae `admission`, `idempotency_key` y `correlation_id` (cabecera `X-Correlation-Id`). `admission` es una `Operation`, con los campos que se describen en [Seguimiento del resultado](#seguimiento-del-resultado). En una emisión aceptada, `estado` es `recibido` y `cod_estado` es 1001 o 1002: con 1001, `clave_acceso` todavía es `None`, y con 1002 ya trae la clave de acceso. Tu código debe aceptar los dos valores. `url_estado` es la URL completa del seguimiento. - `ArchivoComprobante` tiene `contenido` (`bytes`) y `content_type`. Si el comprobante no está autorizado, la API devuelve HTTP `404`, como se explica en [Descargar XML](/v1/guias/consulta-xml). - Los métodos de consultas SRI y `para` lanzan `EcuafactSdkException` sin llamar a la API si el argumento obligatorio está vacío. - Todos los modelos públicos se importan desde `ecuafact`. ## Varios contribuyentes Si no configuras `identificacion` en las opciones, usa los métodos `..._en` o una vista por contribuyente. La vista repite la identificación por ti en cada método. ```python import os from ecuafact import EcuafactClient, EcuafactClientOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: matriz = client.para("0123456789001") perfil = matriz.get_perfil() print(perfil.razon_social, perfil.identificacion) ``` La vista `EcuafactContribuyente` tiene estos métodos, y todos aceptan `opciones=` por nombre. | Método | Equivale a | |---|---| | `emitir(comprobante, idempotency_key=None)` | `client.emitir_en(identificacion, comprobante, idempotency_key)` | | `validar(comprobante)` | `client.validar_en(identificacion, comprobante)` | | `descargar_ride(clave_acceso)` | `client.descargar_ride(identificacion, clave_acceso)` | | `descargar_xml(clave_acceso)` | `client.descargar_xml(identificacion, clave_acceso)` | | `get_perfil()` | `client.get_perfil(identificacion)` | | `actualizar_perfil(cambios)` | `client.actualizar_perfil(identificacion, cambios)` | | `actualizar_logo(contenido, content_type, nombre_archivo)` | `client.actualizar_logo(identificacion, ...)` | | `esperar_resultado(id_operacion, intervalo=5.0, maximo=120.0)` | `client.esperar_resultado(...)` | | `get_consumo()` | `client.get_consumo()` (el cupo es de la API Key, no del contribuyente) | ## Logo del perfil Con `actualizar_logo` puedes subir el logo que aparece en el RIDE de tu contribuyente sin armar la petición `multipart/form-data`; recibes el `PerfilEmisor` actualizado. Acepta PNG o JPEG de hasta 512 KB; `content_type` debe ser `image/png` o `image/jpeg`. Un contenido vacío o un `content_type` vacío lanzan `EcuafactSdkException` sin llamar a la API. Si la subida falla por un corte de red o un estado HTTP transitorio, nuestro SDK la reintenta por ti. ```python import os from ecuafact import EcuafactClient, EcuafactClientOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: with open("logo.png", "rb") as archivo: perfil = client.actualizar_logo("0123456789001", archivo.read(), "image/png", "logo.png") print(f"Logo actualizado para {perfil.razon_social}: {perfil.logo}") ``` Las reglas del archivo y los errores posibles están en [Perfil del emisor](/v1/guias/perfil-emisor). ## Contexto y consumo Antes de emitir puedes preguntar con qué contribuyentes puedes trabajar y cuántos documentos te quedan. `get_contexto()` lee el [contexto](/v1/guias/consulta-contexto) de tu API Key y `get_consumo()` lee tu [cupo](/v1/guias/consumo). Ninguna de las dos consume cupo. ```python import os from ecuafact import EcuafactClient, EcuafactClientOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: contexto = client.get_contexto() for c in contexto.contribuyentes or []: print(c.identificacion, c.puede_emitir, c.tipos_comprobante) cupo = client.get_consumo() print(f"Disponibles {cupo.disponibles} de {cupo.limite_documentos}; vigente hasta {cupo.vigente_hasta}") ``` `get_contexto()` devuelve un `Contexto`. La `identificacion` de cada contribuyente es la completa que devuelve el contexto, y es la que va en las rutas y en `infoTributaria.ruc`. | Campo | Tipo | Descripción | |---|---|---| | `id_cliente` | `str` | Identificador de tu integración. | | `nombre` | `str \| None` | Nombre de tu integración. | | `contribuyentes` | `list[Contribuyente] \| None` | Contribuyentes habilitados para tu API Key en el ambiente de la URL. | | `Contribuyente.identificacion` | `str \| None` | Identificación completa del contribuyente; úsala en las rutas. | | `Contribuyente.puede_emitir` | `bool` | `True` si tu API Key puede emitir para este contribuyente. | | `Contribuyente.puede_recibir` | `bool` | `True` si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión. | | `Contribuyente.tipos_comprobante` | `list[str] \| None` | Códigos de los tipos de comprobante habilitados (`01`, `03`, `04`, `05`, `06`, `07`). | | `Contribuyente.marca_blanca` | `bool` | `True` si el contribuyente es un emisor de marca blanca: sus comprobantes no tienen RIDE, y el XML se descarga igual. | `get_consumo()` devuelve un `QuotaBucket`. Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo, y uno cancelado no lo consume. | Campo | Tipo | Descripción | |---|---|---| | `limite_documentos` | `int` | Documentos contratados en total: la suma de tus paquetes vigentes. | | `reservados` | `int` | Documentos de emisiones recibidas que aún no tienen resultado final. | | `consumidos` | `int` | Documentos descontados por emisiones con resultado final. | | `disponibles` | `int` | Documentos que aún puedes emitir con tus paquetes vigentes. | | `vigente_hasta` | `str` | Fecha y hora (ISO 8601, UTC) en que vence el próximo paquete con saldo. | | `limite_extra`, `reservados_extra`, `consumidos_extra`, `disponibles_extra` | `int` | Se mantienen por compatibilidad y valen 0: todo el saldo está en los cuatro campos anteriores. | El significado de cada valor, con un ejemplo numérico, está en [Consumo y cuotas](/v1/guias/consumo#respuesta). ## Listado de operaciones `listar_operaciones` devuelve una página de los comprobantes emitidos de un contribuyente (`GET /v1/operaciones`) y no consume cupo. `identificacion` es obligatoria (si no la indicas, usa la `identificacion` del cliente); los demás filtros son opcionales y se pasan por nombre: `desde` y `hasta` (`yyyy-MM-dd` o `datetime.date`), `tipo_documento` (un `TipoComprobante`, el código o el nombre del tipo), `buscar` (número, clave de acceso, contraparte o referencia), `pagina` desde 1 y `tamano_pagina` de 1 a 100. Si un filtro no tiene el formato esperado, el SDK lanza `EcuafactSdkException` sin llamar a la API. ```python pagina = 1 while True: resultado = client.listar_operaciones( identificacion="0123456789001", desde="2026-11-01", hasta="2026-11-30", pagina=pagina, tamano_pagina=50, ) for fila in resultado.comprobantes: print(fila.numero_documento, fila.estado, fila.cod_estado, fila.total) if not resultado.hay_mas: break pagina += 1 ``` La respuesta trae `comprobantes`, `pagina`, `tamano_pagina` y `hay_mas`; mientras `hay_mas` sea `True`, pide la página siguiente. Cada fila incluye `clave_acceso`, `numero_documento`, `tipo_documento`, `fecha_emision`, `identificacion_contraparte`, `razon_social_contraparte`, `total`, `estado`, `cod_estado`, `msg_error`, `errores` y `fh_autorizacion`. La vista `client.para(identificacion)` ofrece el mismo método con la identificación fija. ## Consultas SRI Con estos métodos puedes consultar el catastro del SRI, y no consumen cupo. ```python import os from ecuafact import EcuafactClient, EcuafactClientOptions with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: validacion = client.validar_identificacion("0123456789001") contribuyente = client.consultar_contribuyente("0123456789001") encontrados = client.buscar_contribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10) establecimientos = client.listar_establecimientos("0123456789001", "SoloActivos") clave = client.decodificar_clave_acceso("0710202601012345678900110010010000001231234567811") print(validacion.valido, len(encontrados), clave.tipo, clave.secuencial) ``` Los parámetros y las respuestas de cada consulta están en [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). ## Estado del servicio y catálogos Puedes consultar el estado público del servicio y los catálogos del SRI sin armar ninguna petición. `get_estado_servicio()` lee el [estado del servicio](/v1/guias/estado-del-servicio) y no envía API Key, así que sirve para comprobar la disponibilidad antes de configurar una credencial o desde tus propias alertas. `listar_catalogos()` y `get_catalogo(nombre)` leen los [catálogos del SRI](/v1/guias/catalogos) con la API Key del cliente. Los catálogos cambian pocas veces al año, así que puedes guardar sus respuestas en caché por una hora. ```python import os from ecuafact import EcuafactClient, EcuafactClientOptions, EcuafactNotFoundException with EcuafactClient(EcuafactClientOptions( base_address="https://api-sandbox.mynexusapi.com/", api_key=os.environ["ECUAFACT_API_KEY"], )) as client: estado = client.get_estado_servicio() print(estado.estado, estado.disponibilidad_90_dias) for componente in estado.componentes: print(componente.nombre, componente.estado) for incidente in estado.incidentes: print(incidente.inicio, incidente.impacto, incidente.titulo, incidente.fin) for resumen in client.listar_catalogos().catalogos: print(resumen.nombre, resumen.descripcion) try: tarifas = client.get_catalogo("tarifas-iva") except EcuafactNotFoundException: print("Ese catálogo no existe") else: for fila in tarifas.items: print(fila.codigo, fila.descripcion, fila.valor, fila.vigente_desde, fila.vigente_hasta) ``` Si el catálogo `tarifas-iva` existe, el programa imprime una línea por cada código de IVA con su tarifa. Con una clave que no está en el índice, la API responde 404 con el `codEstado` 3013 (`no_encontrado`) y el SDK lanza `EcuafactNotFoundException`. Los demás errores siguen la jerarquía de [Errores](#errores). ### Estado del servicio `get_estado_servicio()` devuelve un `EstadoServicio`. Tiene los mismos campos que la [respuesta de la consulta](/v1/guias/estado-del-servicio#respuesta), en `snake_case`. | Campo | Tipo | Descripción | |---|---|---| | `estado` | `str` | Estado general: `operativo`, `degradado`, `caido` o `sin_datos`. | | `medido_en` | `str \| None` | Momento de la última medición (ISO 8601, UTC). `None` si todavía no hay mediciones. | | `componentes` | `list[ComponenteEstado]` | Componentes monitoreados. | | `disponibilidad_90_dias` | `float \| None` | Porcentaje de minutos sin caída en los últimos 90 días. `None` si aún no hay muestras. | | `incidentes` | `list[IncidentePublico]` | Incidentes de los últimos 90 días y los que siguen abiertos, del más reciente al más antiguo. Lista vacía si no hubo ninguno. | | Campo de `ComponenteEstado` | Tipo | Descripción | |---|---|---| | `nombre` | `str` | Nombre del componente. | | `estado` | `str` | `operativo`, `degradado`, `caido` o `sin_datos`. | | Campo de `IncidentePublico` | Tipo | Descripción | |---|---|---| | `inicio` | `str` | Inicio del incidente (ISO 8601, UTC). | | `fin` | `str \| None` | Fin del incidente. `None` mientras sigue abierto. | | `impacto` | `str` | `degradado` o `caido`. | | `titulo` | `str` | Título breve. | | `detalle` | `str \| None` | Qué significó para tus integraciones. `None` si no hay detalle. | Qué hacer ante cada `estado` se explica en [Valores de estado](/v1/guias/estado-del-servicio#valores-de-estado). Para comprobar que el servicio responde, `get_salud()` llama a `GET /salud`, que no requiere API Key, y devuelve un objeto `Salud` con el código HTTP (`status`) y el cuerpo (`cuerpo`); si la respuesta no es 2xx, lanza la excepción correspondiente. Para conocer el detalle de la disponibilidad, usa [`get_estado_servicio()`](#estado-del-servicio-y-catalogos). ### Catálogos `listar_catalogos()` devuelve un `IndiceCatalogos` y `get_catalogo(nombre)`, un `DetalleCatalogo`. El `nombre` es la clave que devuelve el índice, como `tarifas-iva`; las claves disponibles están en [Catálogos disponibles](/v1/guias/catalogos#catalogos-disponibles). Un `nombre` vacío lanza `EcuafactSdkException` sin llamar a la API. | Campo de `IndiceCatalogos` | Tipo | Descripción | |---|---|---| | `catalogos` | `list[ResumenCatalogo]` | Catálogos disponibles, en el orden de la ficha técnica del SRI. | | Campo de `ResumenCatalogo` | Tipo | Descripción | |---|---|---| | `nombre` | `str` | Clave del catálogo; es el valor que recibe `get_catalogo`. | | `descripcion` | `str` | Descripción breve de lo que contiene. | | Campo de `DetalleCatalogo` | Tipo | Descripción | |---|---|---| | `nombre` | `str` | Clave del catálogo. | | `descripcion` | `str` | Descripción breve del catálogo. | | `fuente` | `str` | Tabla o anexo de la ficha técnica del SRI de donde proviene. | | `items` | `list[ItemCatalogo]` | Filas del catálogo. | | Campo de `ItemCatalogo` | Tipo | Descripción | |---|---|---| | `codigo` | `str` | Código tal como va en el comprobante. Envíalo como texto, con sus ceros a la izquierda cuando los tenga. | | `descripcion` | `str` | Descripción del código. | | `valor` | `float \| None` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. `None` si el catálogo no lo tiene. | | `vigente_desde` | `str \| None` | Primer día de vigencia (`yyyy-MM-dd`). `None` si la fila no está acotada por el inicio. | | `vigente_hasta` | `str \| None` | Último día de vigencia (`yyyy-MM-dd`). `None` si sigue vigente. | | `atributos` | `dict \| None` | Atributos propios del catálogo. `None` si no hay. | ## Siguientes pasos - [Factura](/v1/guias/emision-01): revisa todos los campos y las reglas de cálculo para construir tus comprobantes. - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta qué significa cada `estado` y cada `codEstado`. - [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI sin consultar en bucle. - [Visión general de los SDK](/v1/guias/sdk): compara los cinco SDK y decide entre SDK o HTTP directo. --- # SDK Java Biblioteca oficial para emitir comprobantes desde Java 17 o superior, seguir su autorización, descargar el RIDE y verificar webhooks. Si desarrollas en Java, puedes integrarte con nuestros servicios de facturación usando nuestro SDK para Java. En lugar de armar cada petición HTTP, llamas a métodos como `emitirEn` o `descargarRide`, que reciben y devuelven objetos tipados, en versión síncrona o con `CompletableFuture`. Puedes reintentar sin miedo a duplicar comprobantes, porque el SDK reutiliza la `Idempotency-Key` en sus reintentos; además envía tu API Key en cada llamada, te indica si llegaste al límite de solicitudes o si se agotó tu cupo, y verifica la firma de los webhooks que te enviamos. La guía sigue el orden de una integración. Primero instalas el paquete, configuras el cliente, emites tu primera factura y haces el seguimiento hasta el resultado del SRI; después recibes webhooks y manejas errores, y al final ajustas los reintentos, las opciones por llamada y la conexión, y armas comprobantes con los constructores. La referencia completa está en [Métodos](#metodos). Si todavía no decides entre el SDK y la API por HTTP directo, compáralos en [SDKs](/v1/guias/sdk). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan > `https://api-sandbox.mynexusapi.com`; cambia a `https://api.mynexusapi.com` > solo cuando emitas comprobantes reales. ## 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: ```text Instala el SDK Java de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. 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/sdk-java.md antes de escribir código; no inventes campos. Reutiliza el lenguaje, el gestor de paquetes y la estructura del proyecto; si no hay proyecto, crea uno mínimo. Instala con la dependencia com.ecuafact:sdk:1.0.1 en Maven o Gradle. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Requiere Java 17 o superior. 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 programa e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer. ``` ## Paquete | Dato | Valor | |---|---| | Coordenadas Maven | `com.ecuafact:sdk` | | Versión | `1.0.1` | | Java | 17 o superior | | Dependencias | Jackson Databind `2.18.2`. Es una dependencia transitiva, así que no necesitas declararla. | | Cliente | Síncrono, sobre `java.net.http.HttpClient`, con variantes `*Async` que devuelven `CompletableFuture`. Seguro para uso concurrente. | ## Requisitos - [ ] El JDK 17 o superior, que compruebas con `java -version`, y Maven o Gradle. - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, crea tu sandbox como se explica en [Sandbox de pruebas](/v1/guias/sandbox). - [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier IP. En producción, la IP desde la que ejecutas el código debe estar en **Cuenta > IP permitidas**; si no lo está, la API responde 403 con el `codEstado` 3010 (`ip_no_autorizada`). ## Instalación El paquete se publica en [Maven Central](https://central.sonatype.com/artifact/com.ecuafact/sdk), así que Maven y Gradle lo resuelven sin configurar repositorios adicionales. Con Maven, agrega la dependencia a tu `pom.xml`: ```xml com.ecuafact sdk 1.0.1 ``` Con Gradle y el Kotlin DSL, agrégala en `build.gradle.kts`: ```kotlin dependencies { implementation("com.ecuafact:sdk:1.0.1") } ``` Para comprobar la instalación, ejecuta `mvn dependency:tree` o `gradle dependencies`. Debe aparecer `com.ecuafact:sdk:jar:1.0.1` con `jackson-databind` debajo. ## Configuración Crea el cliente **una vez** y reutilízalo, porque sirve para todos los [contribuyentes](/v1/guias/glosario) de tu API Key. Las opciones se encadenan sobre `EcuafactClientOptions.create(baseAddress, apiKey)`. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import java.time.Duration; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")) .identificacion("0123456789001") // opcional: contribuyente por defecto .timeout(Duration.ofSeconds(60))); // opcional System.out.println(client); // la API Key aparece como *** ``` Si pasas `null` como `apiKey`, el SDK lee la variable de entorno `ECUAFACT_API_KEY`, y si pasas `null` como `baseAddress`, lee `ECUAFACT_BASE_URL`. Con las dos variables definidas basta `new EcuafactClient()` o `EcuafactClientOptions.fromEnvironment()`. Los nombres están en las constantes `EcuafactClientOptions.ENV_API_KEY` y `EcuafactClientOptions.ENV_BASE_URL`. Eliges el ambiente con la URL que configuras, porque el SDK no tiene una opción aparte para eso. Usa `https://api-sandbox.mynexusapi.com/` para pruebas y `https://api.mynexusapi.com/` para producción, **sin** `/v1`, ya que el SDK agrega la versión a cada ruta. | Opción | Tipo | Valor por defecto | Descripción | |---|---|---|---| | `baseAddress` | `String` | `ECUAFACT_BASE_URL` | Primer argumento de `create`. URL `https` absoluta, sin usuario, sin consulta, sin fragmento y sin `/v1`. El SDK rechaza `http`. | | `apiKey` | `String` | `ECUAFACT_API_KEY` | Segundo argumento de `create`. Tu API Key; viaja en la cabecera `X-Api-Key`. No puede tener espacios al inicio o al final ni caracteres de control. No aparece en `toString()`. | | `identificacion` | `String` | `null` | Contribuyente por defecto para `emitir` y `validar` sin identificación. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). | | `validarAntesDeEmitir(boolean)` | `boolean` | `false` | Si es `true`, `emitir` y `emitirEn` llaman antes a `/validar` y solo envían la emisión si la API la da por válida (2 peticiones por emisión). Se explica en [Validar antes de cada emisión](#validar-antes-de-cada-emision). | | `timeout` | `Duration` | `PT30S` (30 s) | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta. Mayor que cero. Por llamada lo cambias con `RequestOptions.timeout(Duration)`. | | `maxResponseBytes` | `Long` | 32 MiB (`33554432`); 100 MiB (`104857600`) en las descargas de RIDE y XML | Tope en bytes del cuerpo de una respuesta. Un valor positivo lo aplica a todas las llamadas, incluidas las descargas; `null` o `0` lo desactiva. Al superarlo lanza `EcuafactResponseTooLargeException` con `limite()` y `bytesLeidos()`. | | `userAgent` | `String` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. No puede estar vacío ni tener caracteres de control. | | `additionalInfo` | `String` | `null` | Texto tuyo que viaja en la cabecera `X-Additional-Info` en cada solicitud a la API. Si es `null` o vacío, no se envía. Admite solo ASCII imprimible (0x20 a 0x7E), sin espacios al inicio o al final y hasta 256 caracteres; el detalle está en [Información adicional](#informacion-adicional). | | `retryTransientFailures` | `boolean` | `true` | Reintenta fallos transitorios (ver [Idempotencia y reintentos](#idempotencia-y-reintentos)). `false` desactiva todo reintento. | | `maxAttempts` | `int` | `3` | Intentos por solicitud, incluido el primero. Debe ser 1 o mayor. | | `respectRetryAfter` | `boolean` | `true` | Espera lo que indique la cabecera `Retry-After` antes de reintentar. | | `maxRetryDelay` | `Duration` | `PT60S` (60 s) | Espera máxima entre reintentos. Con `Duration.ZERO` no hay tope. | | `retryRateLimited` | `boolean` | `true` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`), respetando `Retry-After` y `maxRetryDelay`. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. Un 429 sin el `codEstado` 5005 tampoco se reintenta. | | `retryableStatusCodes` | `Set` | `408`, `425`, `500`, `502`, `503`, `504` | Estados HTTP que se reintentan (valores de 100 a 599). El 429 no va aquí: lo controla `retryRateLimited`. Los valores por defecto están en `EcuafactClientOptions.DEFAULT_RETRYABLE_STATUS_CODES`. | | `retryBaseDelay` | `Duration` | `PT0.2S` (200 ms) | Espera base entre reintentos. No negativa. | | `retryBackoff` | `RetryBackoff` | `RetryBackoff.LINEAR` | `LINEAR`: base x intento (200, 400, 600 ms). `EXPONENTIAL`: base x 2^(intento-1) (200, 400, 800 ms). | | `retryJitter` | `Duration` | `PT0.05S` (50 ms) | Variación aleatoria máxima que se suma a cada espera (en `LINEAR`, multiplicada por el número de intento). No negativa. | | `totalTimeout` | `Duration` | `null` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas. Ver [Idempotencia y reintentos](#idempotencia-y-reintentos). | | `httpClient` | `HttpClient` | `null` | Tu propio `java.net.http.HttpClient`. Si lo pasas, `proxy`, `sslContext`, `executor` y `connectTimeout` se ignoran: configúralos en ese cliente. | | `proxy` | `ProxySelector` | `null` | Proxy, por ejemplo `ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080))`. | | `sslContext` | `SSLContext` | `null` (el del JDK) | Contexto TLS propio: CA corporativa o certificado de cliente. | | `executor` | `Executor` | `null` | Executor del `HttpClient` y de las esperas entre reintentos. Sin valor, el JDK usa el suyo y las esperas usan `ForkJoinPool.commonPool()`. | | `connectTimeout` | `Duration` | `PT10S` (10 s) | Tiempo máximo para abrir la conexión. Mayor que cero. | ```java EcuafactClientOptions.create(baseAddress, apiKey).maxResponseBytes(64L * 1024 * 1024); // null desactiva el tope ``` Cada método de opción valida su valor y lanza `EcuafactConfigurationException` si no es válido, por ejemplo con `maxAttempts(0)`, con un tiempo negativo o con un `additionalInfo` con tildes. Al crear el cliente se validan además la URL y la API Key. Si faltan, si la URL no es una URL `https`, si trae usuario, consulta o fragmento, o si termina en `/v1`, o si la API Key tiene espacios, el constructor lanza la misma excepción antes de hacer cualquier llamada. El mensaje nunca incluye la API Key ni el valor de `additionalInfo`. ## Quickstart: de la API Key al RIDE Este programa hace el flujo completo en el ambiente de pruebas: lee tu [contexto](/v1/guias/consulta-contexto), emite una factura, espera el resultado del SRI con el [seguimiento](/v1/guias/consulta-operacion) y descarga el [RIDE](/v1/guias/glosario), el PDF del comprobante. ### Paso 1. Guarda el comprobante Guarda este JSON como `comprobante.json` en la carpeta desde la que ejecutas el programa, que es la raíz de tu proyecto Maven. Es una factura a consumidor final, con el tipo de identificación `07` y la identificación `9999999999999`, que solo se admite en facturas de hasta 50.00. Factura 10.00 más el IVA del 15 %, que son 1.50, por un total de 11.50. No lleva `secuencial`, porque la plataforma asigna el siguiente [secuencial](/v1/guias/glosario) de la serie `estab`-`ptoEmi`. El programa reemplaza `ruc` por el de tu contexto y `fechaEmision` por la fecha de hoy. ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "07", "identificacionComprador": "9999999999999", "razonSocialComprador": "CONSUMIDOR FINAL", "totalSinImpuestos": 10.00, "totalDescuento": 0.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "baseImponible": 10.00, "valor": 1.50 } ], "propina": 0.00, "importeTotal": 11.50, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 11.50 } ] }, "detalles": [ { "codigoPrincipal": "SERV-001", "descripcion": "Servicio de prueba", "cantidad": 1, "precioUnitario": 10.00, "descuento": 0.00, "precioTotalSinImpuesto": 10.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 10.00, "valor": 1.50 } ] } ] } ``` > [!NOTE] > El cuerpo no lleva `infoTributaria.tipoDocumento`: el tipo lo da la clase que usas, en este caso `FacturaRequest`, como se explica en [Ruta de emisión por tipo de comprobante](#ruta-de-emision-por-tipo-de-comprobante). `estab` y `ptoEmi` deben ser un [establecimiento](/v1/guias/glosario) y un [punto de emisión](/v1/guias/glosario) de tu emisor; el sandbox crea el establecimiento `001` con el punto de emisión `001`. Cada campo está explicado en [Factura](/v1/guias/emision-01). ### Paso 2. Escribe el programa Guarda el código siguiente como `src/main/java/Quickstart.java` en un proyecto Maven que tenga la dependencia de [Instalación](#instalacion). Los modelos del SDK son `record` inmutables, por eso el programa ajusta el JSON con Jackson antes de convertirlo en `FacturaRequest`. El `ObjectMapper` usa `USE_BIG_DECIMAL_FOR_FLOATS` para que los importes no pasen por `double`. El paso 4 usa `esperarResultado`, un método **opcional** que consulta la operación cada 5 segundos hasta tener un resultado final o hasta 2 minutos. En producción puedes usar en cambio el flujo asíncrono, en el que emites, guardas el `idOperacion` y procesas el resultado cuando llega el [webhook](/v1/guias/webhooks). Ese flujo evita que tu proceso se quede esperando. ```java import com.ecuafact.sdk.EcuafactApiException; import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.contracts.ArchivoComprobante; import com.ecuafact.sdk.contracts.Contexto; import com.ecuafact.sdk.contracts.Contribuyente; import com.ecuafact.sdk.contracts.FacturaRequest; import com.ecuafact.sdk.contracts.Operation; import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.nio.file.Files; import java.nio.file.Path; import java.time.LocalDate; import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; public class Quickstart { public static void main(String[] args) throws Exception { EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); ObjectMapper mapper = new ObjectMapper().enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS); try { // 1. Contexto: que contribuyentes puede usar tu API Key. Contexto contexto = client.getContexto(); Contribuyente emisor = contexto.contribuyentes().stream() .filter(Contribuyente::puedeEmitir).findFirst().orElseThrow(); System.out.println("Emisor " + emisor.identificacion()); // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador). ObjectNode json = (ObjectNode) mapper.readTree(Files.readString(Path.of("comprobante.json"))); ((ObjectNode) json.get("infoTributaria")).put("ruc", emisor.identificacion()); ((ObjectNode) json.get("info")).put("fechaEmision", LocalDate.now(ZoneOffset.ofHours(-5)).format(DateTimeFormatter.ofPattern("dd/MM/yyyy"))); FacturaRequest comprobante = mapper.treeToValue(json, FacturaRequest.class); // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key. EmisionResultado emision = client.emitirEn(emisor.identificacion(), comprobante, "FACTURA-2026-0001"); String idOperacion = emision.admission().idOperacion(); // codEstado es 1001 (aun sin clave de acceso) o 1002 (con claveAcceso); acepta los dos. System.out.println("estado " + emision.admission().estado() + " codEstado " + emision.admission().codEstado() + " idOperacion " + idOperacion); // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min). Operation operacion = client.esperarResultado(idOperacion); System.out.println("estado " + operacion.estado() + " codEstado " + operacion.codEstado()); operacion.errores().forEach(detalle -> System.out.println(" - " + detalle)); // 5. RIDE: solo existe cuando el comprobante esta autorizado. if (operacion.esAutorizado()) { ArchivoComprobante ride = client.descargarRide(emisor.identificacion(), operacion.claveAcceso()); Files.write(Path.of("ride.pdf"), ride.contenido()); System.out.println("RIDE guardado en ride.pdf; claveAcceso " + operacion.claveAcceso()); } else if (!operacion.esFinal()) { System.out.println("Aun sin resultado: consulta mas tarde o espera el webhook."); } } catch (EcuafactApiException error) { System.out.println("HTTP " + error.estadoHttp() + " codEstado " + error.codEstado() + ": " + error.msgError()); error.errores().forEach(detalle -> System.out.println(" - " + detalle)); System.out.println("X-Correlation-Id: " + error.correlationId()); } } } ``` ### Paso 3. Ejecuta y verifica Con Maven, ejecuta la clase con el plugin `exec`; también puedes ejecutarla desde tu IDE. ```bash mvn -q compile exec:java -Dexec.mainClass=Quickstart ``` Deberías ver algo como esto; los identificadores cambian en cada ejecución: ``` Emisor 0123456789001 estado recibido codEstado 1001 idOperacion 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f estado autorizado codEstado 2001 RIDE guardado en ride.pdf; claveAcceso 0710202601012345678900110010010000001231234567811 ``` El programa funcionó si ves `estado autorizado` y el ejemplo guardó el RIDE como `ride.pdf`. La tabla explica cada línea que puede imprimir. | Salida | Significado | Qué hacer | |---|---|---| | `estado recibido codEstado 1001` | La API aceptó la emisión y respondió `202 Accepted`. Todavía no es la autorización. La respuesta puede traer 1001, cuando aún no hay clave de acceso y `claveAcceso()` es `null`, o 1002, cuando ya la trae; tu código debe aceptar los dos. Si repetiste la misma `Idempotency-Key` con el mismo cuerpo, recibes la misma operación. | Sigue con el seguimiento. Para emitir otra factura cambia `referenciaExterna` y la `Idempotency-Key`. | | `estado autorizado codEstado 2001` | El SRI autorizó el comprobante; `claveAcceso` trae la [clave de acceso](/v1/guias/glosario) real de 49 dígitos. | Descarga el RIDE o el XML. | | `estado rechazado codEstado 3001` | El SRI rechazó el comprobante. Es un rechazo fiscal, y las líneas que empiezan con `-` muestran el mensaje del SRI, que llega en `errores()`. | Corrige los datos y emite un comprobante nuevo con **nueva** `Idempotency-Key`, nueva `referenciaExterna` y un secuencial nuevo. | | `estado rechazado`, `rechazo_configuracion`, `error` o `cancelado` con otro `codEstado` | La operación terminó sin autorización. | Sigue la fila de su `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion). | | `Aun sin resultado` | Pasaron 2 minutos y el `estado` sigue en `recibido`. | Vuelve a consultar más tarde o espera el [webhook](/v1/guias/webhooks). | | `HTTP 401 codEstado 3009` | La API Key no es válida. | Revisa `ECUAFACT_API_KEY`. | | `HTTP 422 codEstado 3002` | Falta un campo, un campo está mal formado o no se cumple una regla fiscal. Lee las líneas que empiezan con `-`. | Corrige el JSON; un 422 consume 1 documento como intento. | > [!NOTE] > Si ejecutas el programa otro día con la misma `Idempotency-Key`, la fecha > cambia el cuerpo y la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Usa una > `Idempotency-Key` y una `referenciaExterna` nuevas para cada factura nueva. `EmisionResultado` es un `record` con estos métodos: | Método | Tipo | Descripción | |---|---|---| | `admission()` | `Admission` | La respuesta de la emisión, con los mismos campos que `Operation`, que se describen en [Seguimiento y resultado](#seguimiento-y-resultado). En una emisión aceptada, `estado()` es `recibido`: aceptamos el comprobante, que todavía no está autorizado. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde igual. | | `admission().codEstado()` | `Integer` | 1001 si todavía no hay clave de acceso, con `claveAcceso()` en `null`, o 1002 si ya la trae. Tu código debe aceptar los dos valores. | | `admission().idOperacion()` | `String` | UUID de la operación. Guárdalo: lo necesitas para el seguimiento. | | `admission().urlEstado()` | `String` | URL completa del seguimiento de esta operación. | | `idempotencyKey()` | `String` | La `Idempotency-Key` usada (la tuya o la que generó el SDK). | | `correlationId()` | `String` | Cabecera `X-Correlation-Id` de la respuesta. | ## Ruta de emisión por tipo de comprobante Cada tipo de comprobante tiene su propia clase de solicitud, igual que tiene su propio endpoint en la API. El SDK elige la ruta por la clase del objeto que pasas a `emitir`, `emitirEn`, `validar` y `validarEn`, así que no indicas el tipo en ningún otro lugar y el cuerpo de la solicitud no incluye `tipoDocumento`. Las seis clases están en `com.ecuafact.sdk.contracts` y comparten la interfaz `SolicitudComprobante`, que solo agrupa los seis tipos para que el compilador rechace cualquier otro objeto. | Código | Comprobante | Clase | Cabecera y líneas | Ruta de emisión | |---|---|---|---|---| | `01` | Factura | `FacturaRequest` | `InfoFactura`, `DetalleCompraVenta` | `POST /v1/contribuyentes/{identificacion}/facturas` | | `03` | Liquidación de compra | `LiquidacionCompraRequest` | `InfoLiquidacionCompra`, `DetalleCompraVenta` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra` | | `04` | Nota de crédito | `NotaCreditoRequest` | `InfoNotaCredito`, `DetalleNotaCredito` | `POST /v1/contribuyentes/{identificacion}/notas-credito` | | `05` | Nota de débito | `NotaDebitoRequest` | `InfoNotaDebito`, `Motivo` | `POST /v1/contribuyentes/{identificacion}/notas-debito` | | `06` | Guía de remisión | `GuiaRemisionRequest` | `InfoGuiaRemision`, `Destinatario`, `DetalleGuia` | `POST /v1/contribuyentes/{identificacion}/guias-remision` | | `07` | Comprobante de retención | `RetencionRequest` | `InfoComprobanteRetencion`, `DocsSustento`, `RetencionLinea`, `ImpuestoDocSustento` | `POST /v1/contribuyentes/{identificacion}/retenciones` | ```java FacturaRequest factura = ...; EmisionResultado emision = client.emitirEn(identificacion, factura, "FACTURA-2026-0001"); // POST .../facturas ValidacionResultado validacion = client.validarEn(identificacion, factura); // POST .../facturas/validar ``` Todas las clases comparten `InfoTributaria`, `Impuesto`, `Pago` y `CampoAdicional`. Cada clase tiene exactamente las propiedades de su esquema en el contrato, con los mismos nombres, tipos y nulabilidad; los campos que el contrato marca como obligatorios se listan en el Javadoc de cada clase. La validación usa la misma ruta del tipo con `/validar` al final. ## Validar sin emitir Las reglas de negocio de los comprobantes (campos requeridos, formatos de `estab`, `ptoEmi` y `secuencial`, catálogos, topes, coherencia aritmética) viven solo en la API. El SDK no las revisa: `validar` siempre llama a `/validar`, y `emitir` envía el comprobante directo y lanza `EcuafactValidationException` con el 422 de la API. Así, cuando la API cambia una regla no tienes que actualizar el SDK. Antes de emitir puedes comprobar que un comprobante está bien armado con `validarEn(identificacion, comprobante)`, o con `validar(comprobante)` si configuraste la identificación por defecto. El método recibe el mismo request que usarías para emitir, elige la ruta con la clase del comprobante y agrega `/validar`, y aplica las mismas reglas, pero no emite nada, no consume cupo y no necesita `Idempotency-Key`. Te sirve sobre todo cuando generas comprobantes de forma automática: validas el lote, corriges lo que falle y emites después solo lo que pasó. ```java import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.ValidacionResultado; // Dentro de: public static void main(String[] args) throws Exception ValidacionResultado validacion = client.validarEn("0123456789001", comprobante); if (validacion.valido()) { EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001"); System.out.println("Emitido: " + resultado.admission().idOperacion()); } else { System.out.println("Comprobante con errores (codEstado " + validacion.codEstado() + "):"); validacion.errores().forEach(error -> System.out.println("- " + error)); } ``` Cuando el comprobante cumple todas las reglas, `valido()` es `true`. Cuando no las cumple, la API responde lo mismo que respondería al emitirlo, un 422 con el `codEstado` 3002 (`comprobante_invalido`), y el SDK no lanza una excepción: te devuelve `valido()` en `false`, con el código y el problema en `errores()`, para que decidas qué hacer con ese comprobante. Cualquier otro error lanza la misma excepción que en el resto de llamadas, descrita en [Errores](#errores); por ejemplo, si el contribuyente, su RUC o el tipo de comprobante no están habilitados para tu API Key, recibes `EcuafactAuthException` con el `codEstado` 3011 (`acceso_denegado`). Como validar no tiene efectos, el SDK repite la llamada ante un fallo transitorio igual que hace con las consultas. Un resultado válido significa que la emisión no tendrá errores de validación con ese mismo contenido, pero al emitir todavía pueden aparecer otras respuestas, como el cupo agotado o un comprobante duplicado. El detalle de las reglas está en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir) de la guía de emisión. ### Validar antes de cada emisión Si quieres que cada emisión pase primero por `/validar`, activa `EcuafactClientOptions.validarAntesDeEmitir(true)`, o `RequestOptions.create().validarAntes(true)` para una sola llamada (la opción de la llamada reemplaza a la del cliente). Con la opción activa, `emitir` y `emitirEn` (y sus variantes asíncronas) llaman primero a `/validar`: - Si `valido()` es `false` o hay `errores()`, lanzan `EcuafactValidationException` (HTTP 422, `codEstado` 3002) con esos `errores()`, y la emisión no se envía. - Si es válido, envían la emisión y las `advertencias` quedan en `EmisionResultado.advertencias()`. Una advertencia no bloquea. Por defecto es `false`, porque duplica las peticiones: sin la opción, una emisión hace 1 petición; con ella, 2. ```java EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")) .validarAntesDeEmitir(true)); EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001"); resultado.advertencias().forEach(aviso -> System.out.println("Aviso: " + aviso)); ``` `ValidacionResultado` es un `record` con estos métodos: | Método | Tipo | Descripción | |---|---|---| | `valido()` | `boolean` | `true` si el comprobante cumple todas las reglas de la emisión. | | `codEstado()` | `Integer` | `null` si es válido, o 3002 (`CodEstado.COMPROBANTE_INVALIDO`) si no lo es. | | `msgError()` | `String` | Descripción general del código; `null` si es válido. | | `errores()` | `List` | Vacía si es válido; si no, el problema encontrado con la ruta del campo, por ejemplo `$.detalles[0].impuestos[0].valor: Valor de impuesto no coincide con base y tasa.` | | `advertencias()` | `List` | Avisos que la API devuelve junto al resultado (por ejemplo, que ignora la firma de un XML que la trae); vacía si no hay. Un aviso no impide emitir. | ## Seguimiento y resultado Después de emitir tienes un `idOperacion`, y con él consultas la operación hasta que el SRI responde. Puedes hacerlo de tres formas. | Forma | Cuándo usarla | |---|---| | `getOperacion(idOperacion)` (o su alias `consultarOperacion`) | Haces una consulta puntual, por ejemplo desde un proceso programado que revisa las operaciones pendientes. | | `esperarResultado(idOperacion)` / `esperarResultado(idOperacion, intervalo, maximo)` | Necesitas el resultado en el mismo proceso, como en scripts, pruebas o procesos por lotes. Por defecto consulta cada 5 s durante 120 s como máximo. | | [Webhooks](#webhooks) | En producción, recibes el resultado sin consultar en bucle. | `esperarResultado` se detiene en cuanto `esFinal()` es `true` o al agotar `maximo`, y devuelve la **última** lectura, así que revisa `esFinal()` antes de usarla. `intervalo` debe ser mayor que cero y `maximo` no puede ser negativo; si no, lanza `EcuafactSdkException`. Si interrumpes el hilo durante la espera, también lanza `EcuafactSdkException`. `getOperacion`, `consultarOperacion` y `esperarResultado` exigen que `idOperacion` sea un UUID, con o sin guiones; si no lo es, lanzan `EcuafactSdkException` sin llamar a la API. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.EstadoOperacion; import com.ecuafact.sdk.contracts.Operation; import java.time.Duration; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); // Consulta cada 10 s durante 5 minutos como maximo. Operation operacion = client.esperarResultado( "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", Duration.ofSeconds(10), Duration.ofMinutes(5)); String accion = switch (operacion.estadoOperacion()) { case AUTORIZADO -> "Descarga el RIDE con la claveAcceso " + operacion.claveAcceso(); case RECIBIDO, DESCONOCIDO -> "Aun sin resultado: consulta mas tarde o espera el webhook"; default -> "Terminada sin autorizacion: codEstado " + operacion.codEstado() + " " + operacion.msgError() + " " + String.join(" | ", operacion.errores()); }; System.out.println(accion); ``` Reemplaza el `idOperacion` del ejemplo por el que recibiste al emitir. `Operation` es un `record` con los campos de [Seguimiento de una operación](/v1/guias/consulta-operacion). | Método | Tipo | Descripción | |---|---|---| | `estado()` | `String` | `recibido`, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Solo `recibido` no es final. | | `codEstado()` | `Integer` | Código numérico del resultado; su primer dígito es el `estado`. En `recibido` es 1001, sin clave de acceso, o 1002, con `claveAcceso()`; en `autorizado`, 2001; y cuando no se autorizó, el código de la causa, por ejemplo 3001 (`rechazo_sri`) o 4002 (`firma_no_valida`). Compáralo con las constantes de `CodEstado`. | | `msgError()` | `String` | Descripción general y fija del código. `null` con `recibido` y `autorizado`. | | `errores()` | `List` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Nunca es `null` y está vacía si no hay detalle. | | `idOperacion()` | `String` | El identificador que consultaste. | | `urlEstado()` | `String` | URL completa del seguimiento. | | `ambiente()` | `Integer` | `1` = pruebas, `2` = producción. | | `tipoDocumento()` | `String` | Tipo de comprobante (`01` a `07`). | | `numeroDocumento()` | `String` | Número del comprobante, por ejemplo `001-001-000000123`. | | `referenciaExterna()` | `String` | La `referenciaExterna` que enviaste al emitir. | | `claveAcceso()` | `String` | Clave de acceso de 49 dígitos; es `null` con el `codEstado` 1001. | | `fhRecibido()` | `String` | Momento en que la API aceptó la emisión (ISO 8601 con zona horaria). | | `fhAutorizacion()` | `String` | Momento de la autorización del SRI, cuando existe. No la uses para decidir; decide con `estado()`. | ### Estados tipados `Operation`, `Admission` y `Comprobante` conservan los campos de la API (`estado()`, `codEstado()`, `tipoDocumento()`) y agregan métodos tipados. Un valor nuevo de la API no rompe tu código, porque el estado se lee como `DESCONOCIDO` y el tipo de comprobante como `null`, mientras el texto original sigue en el campo `String`. | Método | Tipo | Valores | |---|---|---| | `Operation.estadoOperacion()`, `Comprobante.estadoOperacion()` | `EstadoOperacion` | `RECIBIDO`, `AUTORIZADO`, `RECHAZADO`, `RECHAZO_CONFIGURACION`, `ERROR`, `CANCELADO`, `DESCONOCIDO` | | `Operation.tipoComprobante()`, `Comprobante.tipoComprobante()`, `TipoComprobante.desde(tipoDocumento)` | `TipoComprobante` | `FACTURA` (`01`), `LIQUIDACION_COMPRA` (`03`), `NOTA_CREDITO` (`04`), `NOTA_DEBITO` (`05`), `GUIA_REMISION` (`06`), `RETENCION` (`07`); `null` si el código no se conoce | | `Operation.esFinal()` | `boolean` | `true` si `estado` es cualquier valor distinto de `recibido`. | | `Operation.esAutorizado()` | `boolean` | `true` si `estado` es `autorizado`. | | `WebhookEvent.eventType()` | `TipoEventoWebhook` | `DOCUMENTO_AUTORIZADO`, `DOCUMENTO_RECHAZADO`, `DOCUMENTO_FALLIDO`, `OPERACION_REQUIERE_ATENCION`, `DESCONOCIDO` | `EstadoOperacion` y `TipoComprobante` están en `com.ecuafact.sdk.contracts`; `TipoEventoWebhook`, en `com.ecuafact.sdk`. Cada uno tiene `desde(String)` y `valor()` (`codigo()` en `TipoComprobante`). Los valores de `codEstado` están como constantes `int` en `com.ecuafact.sdk.contracts.CodEstado`, con el nombre de cada código del [catálogo](/v1/guias/errores#catalogo-de-codestado) en mayúsculas, por ejemplo `CodEstado.RECHAZO_SRI` (3001), `CodEstado.COMPROBANTE_INVALIDO` (3002) o `CodEstado.LIMITE_SOLICITUDES` (5005). `CodEstado.estado(codigo)` devuelve el `EstadoOperacion` que corresponde al primer dígito, incluso para un código que tu versión del SDK todavía no conoce, y `CodEstado.nombre(codigo)` devuelve su nombre. ## Webhooks Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle y, antes de procesar cada entrega, comprobar que te la enviamos nosotros. El SDK te ayuda a recibir webhooks: verifica la firma y te entrega el evento tipado, pero no administra los destinos. Los destinos (la URL a la que enviamos cada evento, sus eventos suscritos y su secreto) los administras desde el Portal del Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP o con la API REST, como se explica en [Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api). `WebhookEvent.construir` verifica la cabecera `Ecuafact-Signature` (`t=,v1=`) contra el cuerpo **crudo** y, si es válida, devuelve el evento tipado. Si la firma no coincide, está fuera de la tolerancia (300 s por defecto, `WebhookSignature.DEFAULT_TOLERANCE`) o el cuerpo no es un objeto JSON, lanza `EcuafactWebhookException`. `WebhookSignature.construirEvento(...)` hace lo mismo. | Sobrecarga | Uso | |---|---| | `construir(secreto, cabecera, cuerpo)` | Un solo secreto. `cuerpo` como `String` o `byte[]`. | | `construir(secretos, cabecera, cuerpo)` | Una colección de secretos (rotación). `cuerpo` como `String` o `byte[]`. | | `construir(secretos, cabecera, cuerpo, tolerancia)` | Igual, con otra tolerancia (`Duration`). | Con una colección de secretos, la entrega es válida si coincide con cualquiera, así que puedes rotar el secreto sin rechazar entregas. Agrega el nuevo, publica tu aplicación y quita el anterior cuando las entregas lleguen firmadas con el nuevo, como se explica en [Rotación de secreto](/v1/guias/webhooks-firma#rotacion-de-secreto). El ejemplo siguiente usa el servidor HTTP incluido en el JDK, sin dependencias. Guarda tu secreto en `ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en `ECUAFACT_WEBHOOK_SECRET_ANTERIOR`. Escucha en el puerto 3000, en la ruta `/webhooks/ecuafact`. ```java import com.ecuafact.sdk.EcuafactWebhookException; import com.ecuafact.sdk.WebhookEvent; import com.ecuafact.sdk.WebhookSignature; import com.sun.net.httpserver.HttpServer; import java.net.InetSocketAddress; import java.util.List; import java.util.Objects; import java.util.stream.Stream; public class Webhook { public static void main(String[] args) throws Exception { List secretos = Stream.of( System.getenv("ECUAFACT_WEBHOOK_SECRET"), System.getenv("ECUAFACT_WEBHOOK_SECRET_ANTERIOR")) .filter(Objects::nonNull).filter(s -> !s.isEmpty()).toList(); HttpServer servidor = HttpServer.create(new InetSocketAddress(3000), 0); servidor.createContext("/webhooks/ecuafact", intercambio -> { byte[] cuerpoCrudo = intercambio.getRequestBody().readAllBytes(); String cabecera = intercambio.getRequestHeaders().getFirst(WebhookSignature.HEADER); int estado; try { WebhookEvent evento = WebhookEvent.construir(secretos, cabecera == null ? "" : cabecera, cuerpoCrudo); // Deduplica por eventTypeRaw + resourceId antes de procesar y responde 2xx. switch (evento.eventType()) { case DOCUMENTO_AUTORIZADO -> System.out.println("Autorizado " + evento.idOperacion() + " " + evento.claveAcceso()); case DOCUMENTO_RECHAZADO -> System.out.println("Rechazo fiscal " + evento.idOperacion() + " codEstado " + evento.codEstado() + " " + evento.errores()); case DOCUMENTO_FALLIDO -> System.out.println("No emitido " + evento.idOperacion() + " " + evento.estado() + " codEstado " + evento.codEstado()); default -> System.out.println("Evento " + evento.eventTypeRaw() + " prueba=" + evento.probe()); } estado = 200; } catch (EcuafactWebhookException error) { estado = 401; } intercambio.sendResponseHeaders(estado, -1); intercambio.close(); }); servidor.start(); } } ``` Para comprobarlo, pulsa **Probar** en tu destino del portal, que envía el evento de prueba. Tu consola muestra `Evento operation.requires_attention prueba=true` y la entrega aparece en **Entregas** con un 200. Si ves un 401, el secreto no coincide o el reloj del servidor está desfasado más de 300 s. | Método de `WebhookEvent` | Tipo | Descripción | |---|---|---| | `eventType()` | `TipoEventoWebhook` | Tipo de evento; un valor nuevo se lee como `DESCONOCIDO`. | | `eventTypeRaw()` | `String` | Valor original de `eventType` (`document.authorized`, `document.rejected`, `document.failed`, `operation.requires_attention`). | | `resourceId()` | `String` | Recurso del evento. Con `eventTypeRaw()` forma la clave de deduplicación. | | `occurredAtUtc()` | `Instant` | Momento del evento; `null` si no vino o no se pudo leer. | | `idOperacion()` | `String` | Operación a la que pertenece el evento. | | `estado()` | `String` | El mismo `estado` del seguimiento en eventos `document.*`: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`. Su versión tipada es `estadoOperacion()`. | | `tipoDocumento()` | `String` | Tipo de comprobante (`01` a `07`), cuando el evento lo trae. | | `claveAcceso()` | `String` | Clave de acceso del comprobante, si aplica. | | `codEstado()` | `Integer` | Código numérico del resultado, por ejemplo 2001 en `document.authorized`, 3001 (`rechazo_sri`) en `document.rejected` o 4002 (`firma_no_valida`) en `document.failed`. Decide con `estado()` y `codEstado()`, no solo con el tipo del evento. | | `msgError()` | `String` | Descripción fija del código; `null` cuando no hay error. | | `errores()` | `List` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacía si no hay detalle. | | `fhAutorizacion()` | `String` | Momento de la autorización del SRI, cuando existe. | | `ruc()` | `String` | RUC del documento; en el evento de prueba, el RUC al que se limita el destino. `null` si no viene. | | `probe()` | `boolean` | `true` en el evento de prueba del portal. | Si solo necesitas saber si la firma es válida, usa `WebhookSignature.verify(secretos, cabecera, cuerpo)`, que devuelve `boolean` y nunca lanza; acepta un secreto o una colección, y el cuerpo como `String` o `byte[]`. Después lee el evento con `WebhookEvent.parse(cuerpo)`. ### Standard Webhooks Cada entrega trae además las cabeceras del estándar [Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks) (`webhook-id`, `webhook-timestamp` y `webhook-signature`), que corresponden a la misma firma. Con el SDK puedes verificar cualquiera de las dos, sin decidir cuál llegó. | Método | Qué hace | |---|---| | `WebhookEvent.construirConCabeceras(secretos, cabeceras, cuerpo)` | Devuelve el `WebhookEvent` si `Ecuafact-Signature` o Standard Webhooks es válida; si no, lanza `EcuafactWebhookException`. Con otro `Duration` al final cambia la tolerancia. `cabeceras` es un `Map` cuyos nombres no distinguen mayúsculas. | | `WebhookSignature.verificarCualquiera(secretos, cabeceras, cuerpo)` | Devuelve `boolean` con la misma regla y nunca lanza. También acepta un único secreto y, en lugar del mapa, una `Function` que lee una cabecera por nombre. | | `WebhookSignature.verificarEstandar(secretos, webhookId, webhookTimestamp, webhookSignature, cuerpo)` | Devuelve `boolean`. Verifica solo la firma de Standard Webhooks. | | `WebhookSignature.firmarEstandar(secreto, webhookId, webhookTimestamp, cuerpo)` | Devuelve el valor de `webhook-signature` (`v1,`). Sirve para pruebas automatizadas. | El secreto puede llevar o no el prefijo `whsec_`, y también aceptas una colección de secretos para la rotación. Con el servidor HTTP del JDK, `getRequestHeaders()` sirve como `cabeceras`. ```java WebhookEvent evento = WebhookEvent.construirConCabeceras(secretos, intercambio.getRequestHeaders(), cuerpoCrudo); ``` ### Probar tu receptor sin esperar una entrega Para probar tu receptor en un test automatizado, firma un cuerpo de ejemplo con el mismo secreto y comprueba que lo aceptas. Con `WebhookSignature.sign` generas la cabecera `Ecuafact-Signature`, y con `firmarEstandar`, la de Standard Webhooks. ```java String secreto = "secreto-de-prueba"; String cuerpo = "{\"eventType\":\"document.authorized\",\"resourceId\":\"r1\",\"estado\":\"autorizado\",\"codEstado\":2001}"; long ahora = java.time.Instant.now().getEpochSecond(); String cabecera = WebhookSignature.sign(secreto, ahora, cuerpo); WebhookEvent evento = WebhookEvent.construir(secreto, cabecera, cuerpo); // evento.eventType() == TipoEventoWebhook.DOCUMENTO_AUTORIZADO // Una firma vencida, alterada o de otro secreto lanza EcuafactWebhookException. ``` > [!WARNING] > Verifica la firma sobre el cuerpo crudo. En Spring, recibe el cuerpo como > `@RequestBody byte[]` o `@RequestBody String` (no como objeto) para conservar > los bytes exactos. Los eventos y su contenido están en [Webhooks](/v1/guias/webhooks), y el algoritmo de la firma, en [Verificación de firma](/v1/guias/webhooks-firma). ## Errores Todas las excepciones son `RuntimeException`, así que no necesitas declararlas, y heredan de `EcuafactSdkException`. Las que vienen de una respuesta de la API heredan además de `EcuafactApiException`. Captura primero las específicas y al final `EcuafactSdkException`, que atrapa cualquier error del SDK. | Excepción | Hereda de | Cuándo ocurre | Qué hacer | |---|---|---|---| | `EcuafactConfigurationException` | `EcuafactSdkException` | Falta la API Key o la URL, la URL no es `https`, trae usuario, consulta o fragmento, o termina en `/v1`, la API Key tiene espacios o caracteres de control, o una opción es inválida (`maxAttempts(0)`, tiempo negativo, `correlationId` o `additionalInfo` inválido). | Corrige la configuración. No llama a la API. | | `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API tras agotar los intentos. | Reintenta más tarde con la misma `idempotencyKey()`. Usa `correlationId()` para ubicar la llamada en tus registros. | | `EcuafactTimeoutException` | `EcuafactSdkException` | El último intento superó `timeout`, o se agotó `totalTimeout` antes de un intento. | Reintenta con la misma `idempotencyKey()`; si emitías, consulta antes el seguimiento. Usa `correlationId()` para ubicar la llamada en tus registros. | | `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida, o cuerpo vacío o que no es un objeto JSON. | Responde 401 y no proceses el evento. | | `EcuafactAuthException` | `EcuafactApiException` | HTTP 401 o 403, con el `codEstado` 3009 (`credenciales_invalidas`), 3010 (`ip_no_autorizada`) o 3011 (`acceso_denegado`). | Corrige la API Key, registra la IP o revisa que el contribuyente y el tipo estén habilitados. | | `EcuafactValidationException` | `EcuafactApiException` | HTTP 400, 413, 415, 422 o 501: solicitud rechazada, con el `codEstado` 3002 (`comprobante_invalido`), 3003 (`solicitud_invalida`), 3006 (`cuerpo_excedido`), 3007 (`version_no_soportada`), 3008 (`no_implementado`) o 3012 (`filtros_invalidos`). | Corrige según `errores()`. Un 422 con el `codEstado` 3002 no consume cupo. | | `EcuafactNotFoundException` | `EcuafactApiException` | HTTP 404, con el `codEstado` 3013 (`no_encontrado`), o con `codEstado()` en 0 si la ruta no existe y la respuesta no trae cuerpo de error. | Verifica el `idOperacion` o la `claveAcceso`. | | `EcuafactConflictException` | `EcuafactApiException` | HTTP 409, con el `codEstado` 3004 (`comprobante_duplicado`), 3005 (`conflicto_idempotencia`) o 3014 (`correo_no_disponible`). | Mira el `codEstado()` en la tabla de códigos de abajo. | | `EcuafactRateLimitException` | `EcuafactApiException` | HTTP 429 con un `codEstado` distinto de 4004, normalmente 5005 (`limite_solicitudes`). | Espera `retryAfter()` y reintenta con la misma `idempotencyKey()`. El SDK ya lo reintenta por defecto, así que la excepción llega cuando se agotan los intentos o si usaste `retryRateLimited(false)`. | | `EcuafactQuotaException` | `EcuafactApiException` | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`): cupo agotado. | Amplía el cupo ([`GET /v1/consumo`](/v1/guias/consumo)). No reintentes. | | `EcuafactServerException` | `EcuafactApiException` | HTTP 5xx, con el `codEstado` 5001 (`error_interno`), 5002 (`servicio_no_disponible`), 5003 (`error_dependencia`) o 5004 (`tiempo_agotado`), tras agotar los intentos si el estado es reintentable. | Si `esReintentable()` es `true`, reintenta más tarde con la misma `idempotencyKey()`. | | `EcuafactApiException` | `EcuafactSdkException` | Cualquier otro estado de error de la API que no corresponda a las filas anteriores (por ejemplo, un 418). | Revisa `codEstado()`, `msgError()` y `errores()`. | | `EcuafactTipoComprobanteException` | `EcuafactSdkException` | El filtro `tipoDocumento` de `listarOperaciones` no es un tipo conocido. `emitir` y `validar` no la lanzan: el tipo lo da la clase del comprobante. | Usa un nombre (`factura`, `liquidacion`, `nota-credito`, `nota-debito`, `guia`, `retencion`) o un código (`01`, `03` a `07`). No llama a la API. | | `EcuafactResponseTooLargeException` | `EcuafactSdkException` | El cuerpo de la respuesta supera el tope `maxResponseBytes`. Trae `limite()` y `bytesLeidos()`. | Sube el tope o desactívalo si esperas archivos más grandes. No se reintenta. | | `EcuafactSdkException` | `RuntimeException` | Otros errores locales: `Idempotency-Key` inválida, `idOperacion` que no es UUID, falta el contribuyente por defecto o un parámetro obligatorio, `identificacion` que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, `.` o `..`, hilo interrumpido, llamada cancelada, o una respuesta 2xx vacía o ilegible. | Corrige la llamada. Si ocurre al emitir, repite la emisión con la `idempotencyKey()` de la excepción, como se explica en [Idempotencia y reintentos](#idempotencia-y-reintentos). | | Método de `EcuafactApiException` | Tipo | Descripción | |---|---|---| | `codEstado()` | `int` | Código numérico del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), por ejemplo 3002 o 3004. Úsalo para decidir, comparándolo con las constantes de `CodEstado`. Es 0 si la respuesta no traía JSON. | | `estado()` | `String` | `estado` de la respuesta de error, como `rechazado`, `rechazo_configuracion` o `error`; `null` si la respuesta no traía JSON. | | `msgError()` | `String` | Descripción general y fija del código. Muéstrala o regístrala, pero no la uses para decidir. | | `estadoHttp()` | `int` | Estado HTTP. | | `errores()` | `List` | Detalle específico del error, como la ruta del campo que falla en un 3002. Nunca es `null` y está vacía cuando no hay detalle. | | `correlationId()` | `String` | Cabecera `X-Correlation-Id`. Inclúyelo al pedir soporte. | | `idempotencyKey()` | `String` | Clave usada en la emisión; reutilízala al reintentar. Todas las excepciones del SDK la exponen. | | `retryAfter()` | `Duration` | Espera indicada por la cabecera `Retry-After`; `null` si no llegó. | | `esReintentable()` | `boolean` | `true` si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el `codEstado` 5005. El 429 con 4004 (cupo agotado) no es reintentable. | `EcuafactConnectionException` y `EcuafactTimeoutException` no traen respuesta de la API, así que no tienen `codEstado()`. Exponen `idempotencyKey()` y `correlationId()`, que devuelve el `X-Correlation-Id` que enviaste con `RequestOptions.correlationId(String)`, o `null` si no enviaste uno. ```java import com.ecuafact.sdk.EcuafactApiException; import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EcuafactConnectionException; import com.ecuafact.sdk.EcuafactQuotaException; import com.ecuafact.sdk.EcuafactRateLimitException; import com.ecuafact.sdk.EcuafactTimeoutException; import com.ecuafact.sdk.EcuafactValidationException; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.contracts.FacturaRequest; import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.ObjectMapper; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); FacturaRequest comprobante = new ObjectMapper() .enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS) .readValue(Files.readString(Path.of("comprobante.json")), FacturaRequest.class); try { EmisionResultado r = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001"); System.out.println(r.admission().estado() + " " + r.admission().idOperacion()); } catch (EcuafactValidationException error) { // Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual. error.errores().forEach(System.out::println); } catch (EcuafactQuotaException error) { System.out.println("Cupo agotado: compra un paquete. No reintentes."); } catch (EcuafactRateLimitException error) { System.out.println("Limite de solicitudes: espera " + error.retryAfter() + " y reintenta con " + error.idempotencyKey()); } catch (EcuafactApiException error) { System.out.println(error.estadoHttp() + " codEstado " + error.codEstado() + " " + error.msgError() + " " + error.errores() + " reintentable=" + error.esReintentable() + " correlation=" + error.correlationId()); } catch (EcuafactConnectionException | EcuafactTimeoutException error) { // Sin conexion o sin respuesta: reintenta mas tarde con la MISMA Idempotency-Key. System.out.println(error.getMessage() + " clave=" + error.idempotencyKey()); } ``` Estos son los códigos que verás con más frecuencia. El catálogo completo, con el nombre de cada código, está en [Errores](/v1/guias/errores#catalogo-de-codestado), y las constantes de `CodEstado` llevan ese mismo nombre, escrito con la convención del lenguaje. | `codEstado` | Nombre | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---|---| | 3009 | `credenciales_invalidas` | 401 | API Key ausente o inválida. | Corrige la API Key. No reintentes sin cambiar nada. | | 3010 | `ip_no_autorizada` | 403 | La IP no está permitida o no se pudo identificar. | Registra tu IP en **Cuenta > IP permitidas** o llama directo a la URL de la API, sin proxies intermedios; si persiste, contacta a soporte con el `correlationId()`. | | 3011 | `acceso_denegado` | 403 | Contribuyente, tipo de comprobante no habilitado, o `infoTributaria.ruc` no coincide con el contribuyente de la ruta. | Revisa `getContexto()` (`puedeEmitir()`, `tiposComprobante()`). | | 5005 | `limite_solicitudes` | 429 | Superaste el límite de solicitudes por minuto. | Espera `retryAfter()` y reintenta con la misma `Idempotency-Key`, aunque el SDK ya lo hace por defecto; reduce el ritmo. | | 3003 | `solicitud_invalida` | 400 | Cabeceras inválidas (por ejemplo, `Idempotency-Key` con caracteres no permitidos) o JSON mal formado. | Corrige según `errores()`. | | 3002 | `comprobante_invalido` | 422 | Campos del comprobante faltantes o mal formados, campos desconocidos o de otro tipo, o una regla fiscal incumplida (totales, impuestos). | Corrige según `errores()`; consume 1 documento como intento. | | 3012 | `filtros_invalidos` | 400 | Filtro de consulta fuera de rango (fechas o `max`). | Ajusta los filtros. | | 3006 | `cuerpo_excedido` | 413 | Cuerpo mayor a 2 MiB en la emisión (1 MiB en otros `POST`/`PUT`). | Reduce el cuerpo. | | 3004 | `comprobante_duplicado` | 409 | Ya existe un comprobante con ese número recibido, autorizado o rechazado por el SRI. | No reenvíes; si querías otro comprobante, usa otro `secuencial` u omítelo para que se asigne el siguiente. | | 3005 | `conflicto_idempotencia` | 409 | Misma `Idempotency-Key` o `referenciaExterna` con otro contenido. | Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. | | 4004 | `cupo_agotado` | 429 | Se agotó el cupo de documentos. El SDK no lo reintenta. | Revisa `getConsumo()`; compra un paquete. | | 3013 | `no_encontrado` | 404 | Operación, comprobante o RIDE no encontrado. | Verifica el id o la clave; el RIDE existe solo si está autorizado. | | 5001, 5002, 5003, 5004 | `error_interno`, `servicio_no_disponible`, `error_dependencia`, `tiempo_agotado` | 500, 503, 502, 504 | Error interno, servicio no disponible, o el servicio de validación fiscal falló o no respondió. | El SDK ya reintentó; vuelve a intentar más tarde con la misma `Idempotency-Key`. | ## Idempotencia y reintentos La `Idempotency-Key` evita emitir dos veces el mismo comprobante si una llamada se repite, por ejemplo después de un timeout o de una caída de la red. - Si no la pasas, o pasas `null` o un texto vacío, el SDK genera un UUID sin guiones, lo usa en todos sus reintentos y te la devuelve en `resultado.idempotencyKey()` o, si falla, en `error.idempotencyKey()`. - Te recomendamos pasar un valor estable por intención, como tu número interno de factura, o un UUID v4 que guardes junto al documento. - El SDK valida la clave antes de enviarla con la misma regla de la API: de 1 a 128 caracteres, solo letras, dígitos y `-` `_` `.` `:` `/`. Si no cumple, lanza `EcuafactSdkException` sin llamar a la API. > [!WARNING] > Si reintentas una emisión desde tu aplicación, reutiliza la misma > `Idempotency-Key`. Una clave nueva para el mismo comprobante puede duplicar la > emisión. Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción (`EcuafactSdkException`) conserva la `Idempotency-Key` en `idempotencyKey()` y en su mensaje trae el `X-Correlation-Id` de la solicitud; repite la emisión con esa misma clave y no se duplica el comprobante. | Situación | Se reintenta | Detalle | |---|---|---| | HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con `retryableStatusCodes`. Solo en `GET` y en `POST`/`PUT` con `Idempotency-Key` (la emisión siempre la lleva). | | HTTP 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí, salvo con `retryRateLimited(false)` | Espera lo que indica `Retry-After` y reintenta. Con `retryRateLimited(false)` lanza `EcuafactRateLimitException` con `retryAfter()`, y decides tú cuándo reintentar. Un 429 sin el `codEstado` 5005, por ejemplo de un proxy intermedio, no se reintenta. | | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`) | Nunca | Esperar no repone el cupo. Lanza `EcuafactQuotaException`. | | Error de red o timeout de un intento | Sí | Se reintenta en las mismas condiciones; al agotar los intentos lanza `EcuafactConnectionException` o `EcuafactTimeoutException`. | | Descarga de RIDE/XML y consultas | Sí | Como son `GET`, se reintentan ante un estado HTTP transitorio o un error de red. | | Validación sin emitir (`validar`, `validarEn`) | Sí | Se reintenta como una consulta ante un estado HTTP transitorio o un error de red. No lleva `Idempotency-Key` porque no emite nada. | | `actualizarPerfil`, `actualizarLogo` | No | No llevan `Idempotency-Key`, así que un reintento automático podría repetir el efecto. | | Cualquier otro 4xx | No | Se lanza la excepción de inmediato. | Antes del reintento número *n*, el SDK espera según estas reglas: - `LINEAR`: `retryBaseDelay` x *n* más un margen aleatorio de hasta `retryJitter` x *n*. - `EXPONENTIAL`: `retryBaseDelay` x 2^(*n*-1) más un margen aleatorio de hasta `retryJitter`. - Si la respuesta trae un `Retry-After` mayor y `respectRetryAfter` es `true`, espera ese tiempo. - La espera nunca supera `maxRetryDelay`, salvo que ese valor sea `Duration.ZERO`. Con `totalTimeout`, cada intento se acorta al tiempo que queda. Si la siguiente espera no cabe dentro del tope, el SDK no reintenta y lanza la excepción del último intento; si el tope ya se agotó antes de un intento, lanza `EcuafactTimeoutException`. Si interrumpes el hilo durante una llamada síncrona, el SDK cancela la solicitud y lanza `EcuafactSdkException`. ## Opciones por llamada Puedes cambiar el tiempo máximo, el tope total, la correlación, los reintentos o la información adicional de una sola llamada sin tocar la configuración del cliente. Lo que no indiques usa la configuración del cliente. Los métodos que llaman a la API tienen una sobrecarga con `RequestOptions` como último parámetro, también en la vista `para(...)` y `esperarResultado`. Algunas sobrecargas exigen además los parámetros anteriores. - Emisión: `emitir(comprobante, idempotencyKey, opciones)` y `emitirEn(identificacion, comprobante, idempotencyKey, opciones)`; pasa `null` como `idempotencyKey` para que el SDK la genere. - Espera: `esperarResultado(idOperacion, intervalo, maximo, opciones)`; `opciones` se aplica a cada consulta. | Método de `RequestOptions` | Qué hace | |---|---| | `RequestOptions.create()` | Crea las opciones vacías. | | `timeout(Duration)` | Tiempo máximo de cada intento, solo en esta llamada. Mayor que cero. | | `totalTimeout(Duration)` | Tope de esta llamada, incluidos reintentos y esperas. Mayor que cero. | | `correlationId(String)` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres: letras, dígitos y `.` `_` `-`. | | `reintentos(false)` | Un solo intento en esta llamada. `reintentos(true)` aplica la política del cliente: no activa reintentos si el cliente los tiene desactivados. | | `validarAntes(boolean)` | Solo en `emitir` y `emitirEn`: `true` llama a `/validar` antes de emitir y `false` no lo llama, sea cual sea `validarAntesDeEmitir` del cliente. | | `additionalInfo(String)` | Valor de la cabecera `X-Additional-Info` solo en esta llamada; reemplaza el del cliente. Con una cadena vacía o `null` no se envía la cabecera en esta llamada. Mismas reglas que la opción del cliente. | La API devuelve la correlación que enviaste. La encuentras en `EmisionResultado.correlationId()` y en `EcuafactApiException.correlationId()`. Úsala para relacionar tus registros con los nuestros y para pedirnos soporte. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.RequestOptions; import com.ecuafact.sdk.contracts.ArchivoComprobante; import com.ecuafact.sdk.contracts.Contexto; import java.nio.file.Files; import java.nio.file.Path; import java.time.Duration; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); // Un solo intento y correlacion propia para esta consulta. Contexto contexto = client.getContexto(RequestOptions.create() .reintentos(false) .correlationId("pedido-2026-0457")); System.out.println("Contribuyentes: " + contexto.contribuyentes().size()); // Mas tiempo para una descarga grande, con tope total de 2 minutos. ArchivoComprobante ride = client.descargarRide( "0123456789001", "0710202601012345678900110010010000001231234567811", RequestOptions.create().timeout(Duration.ofSeconds(60)).totalTimeout(Duration.ofMinutes(2))); Files.write(Path.of("ride.pdf"), ride.contenido()); ``` Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu emisor. Si pasas un valor inválido, como un `correlationId` con espacios o de más de 64 caracteres, un `additionalInfo` fuera de sus reglas o un tiempo menor o igual a cero, el SDK lanza `EcuafactConfigurationException` al armar las opciones, sin llamar a la API. ### Variantes asíncronas y cancelación Los métodos que llaman a la API tienen una variante `*Async` que devuelve un `CompletableFuture` (por ejemplo `emitirEnAsync`, `getOperacionAsync`, `descargarRideAsync` y `esperarResultadoAsync`). - `cancel(true)` aborta la solicitud HTTP en curso y los reintentos pendientes. Lo mismo ocurre si el futuro termina por otra vía antes de la respuesta, por ejemplo con `orTimeout(...)` o `completeExceptionally(...)`. - Los argumentos inválidos, como una `Idempotency-Key` mal formada, lanzan la excepción de inmediato, antes de devolver el futuro. - Los errores de la API completan el futuro con la excepción del SDK como causa, que lees con `ExecutionException.getCause()` en `get()` y con `CompletionException.getCause()` en `join()`. - `esperarResultadoAsync(idOperacion, intervalo, maximo, opciones)` consulta sin bloquear hilos entre consultas y se cancela igual. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EcuafactSdkException; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.RequestOptions; import com.ecuafact.sdk.contracts.FacturaRequest; import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.ObjectMapper; import java.nio.file.Files; import java.nio.file.Path; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); FacturaRequest comprobante = new ObjectMapper() .enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS) .readValue(Files.readString(Path.of("comprobante.json")), FacturaRequest.class); CompletableFuture envio = client.emitirEnAsync( "0123456789001", comprobante, "FACTURA-2026-0002", RequestOptions.create().correlationId("pedido-2026-0458")); try { // Espera 30 s como maximo. EmisionResultado r = envio.get(30, TimeUnit.SECONDS); System.out.println(r.admission().estado() + " " + r.admission().idOperacion()); } catch (TimeoutException tiempo) { // Sin respuesta en 30 s: cancela el intento en curso y los reintentos pendientes. envio.cancel(true); System.out.println("Cancelada: reintenta despues con la misma Idempotency-Key"); } catch (ExecutionException error) { if (error.getCause() instanceof EcuafactSdkException sdk) { System.out.println("Error del SDK: " + sdk.getMessage() + " clave=" + sdk.idempotencyKey()); } } ``` Si cancelas una emisión, no sabes si la API la recibió. Reintenta después con la **misma** `Idempotency-Key` y el mismo cuerpo. Si ya se había recibido, la API responde con el mismo `idOperacion` y el estado actual de la operación. En lugar de `get(30, TimeUnit.SECONDS)` y `cancel(true)` puedes encadenar `orTimeout`. Al vencer el tiempo, el futuro termina con `TimeoutException` y el SDK aborta la solicitud en curso. ```java import com.ecuafact.sdk.EmisionResultado; import java.util.concurrent.TimeUnit; EmisionResultado r = client.emitirEnAsync("0123456789001", comprobante, "FACTURA-2026-0002", null) .orTimeout(30, TimeUnit.SECONDS) .join(); // CompletionException con TimeoutException como causa si vence ``` ## Información adicional Puedes enviar un dato tuyo en cada solicitud, por ejemplo la versión de tu ERP o la sucursal que emite, para que ubiquemos tus llamadas cuando nos pidas soporte. Viaja en la cabecera `X-Additional-Info`; la API la asocia a tu solicitud y no cambia su respuesta. Es la única cabecera personalizada que admite el SDK. Las reglas de la API están en [Límites](/v1/guias/limites#cabeceras). | Dónde | Qué hace | |---|---| | `EcuafactClientOptions.additionalInfo(String)` | Se envía en todas las solicitudes del cliente, incluidas las de `esperarResultado`, `esperarResultadoAsync` y la vista `para(...)`. | | `RequestOptions.additionalInfo(String)` | Reemplaza el valor del cliente solo en esa llamada. Si no lo llamas, se usa el del cliente; con cadena vacía o `null` no se envía la cabecera en esa llamada. | El SDK valida el valor en tu proceso, antes de llamar a la API, con estas reglas: - Solo caracteres ASCII imprimibles (0x20 a 0x7E): sin tildes, `ñ` ni saltos de línea. - Sin espacios al inicio ni al final. - Máximo 256 caracteres. Si no cumple, el método lanza `EcuafactConfigurationException` sin llamar a la API. El valor no aparece en `toString()` de las opciones ni del cliente, ni en los mensajes de las excepciones. No pongas en él la API Key ni datos personales. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.RequestOptions; import com.ecuafact.sdk.contracts.Contexto; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")) .additionalInfo("erp=MiERP/4.2; sucursal=001")); // Todas las solicitudes llevan X-Additional-Info: erp=MiERP/4.2; sucursal=001 Contexto contexto = client.getContexto(); // Solo esta llamada lleva otro valor. Contexto otro = client.getContexto(RequestOptions.create() .additionalInfo("erp=MiERP/4.2; sucursal=002; lote=2026-10-08")); System.out.println("Contribuyentes: " + contexto.contribuyentes().size()); ``` | Error | Por qué pasa | Qué hacer | |---|---|---| | `EcuafactConfigurationException` al configurar el cliente | `additionalInfo` tiene tildes, `ñ`, saltos de línea u otro carácter fuera de 0x20 a 0x7E, espacios al inicio o al final, o más de 256 caracteres. | Corrige el valor: quita tildes y espacios de los extremos y acórtalo. | | `EcuafactConfigurationException` al armar `RequestOptions` | El mismo problema en `RequestOptions.additionalInfo(String)`. No se llamó a la API. | Corrige el valor de esa llamada. | ## Conexión: proxy, TLS y HttpClient propio Si necesitas salir por un proxy corporativo, confiar en una CA propia o usar un certificado de cliente, puedes configurarlo con `proxy`, `sslContext`, `executor` y `connectTimeout`. Si no indicas nada, el SDK crea su propio `java.net.http.HttpClient` con un `connectTimeout` de 10 s. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.RetryBackoff; import java.net.InetSocketAddress; import java.net.ProxySelector; import java.time.Duration; import javax.net.ssl.SSLContext; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")) .retryBackoff(RetryBackoff.EXPONENTIAL) .retryBaseDelay(Duration.ofMillis(500)) .retryRateLimited(true) .totalTimeout(Duration.ofSeconds(60)) .proxy(ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080))) .sslContext(SSLContext.getDefault()) .connectTimeout(Duration.ofSeconds(5))); System.out.println(client.getContexto().contribuyentes().size() + " contribuyentes"); ``` Si ya tienes un `HttpClient` configurado (por ejemplo, compartido con otras integraciones), pásalo con `httpClient(...)`. En ese caso el SDK no crea el suyo e ignora `proxy`, `sslContext`, `executor` y `connectTimeout`. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import java.net.InetSocketAddress; import java.net.ProxySelector; import java.net.http.HttpClient; import java.time.Duration; // Dentro de: public static void main(String[] args) throws Exception HttpClient http = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(5)) .proxy(ProxySelector.of(new InetSocketAddress("proxy.miempresa.local", 8080))) .build(); EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")) .httpClient(http)); System.out.println(client.getContexto().contribuyentes().size() + " contribuyentes"); ``` El `timeout` por intento y los reintentos siguen siendo los de `EcuafactClientOptions` aunque pases tu propio `HttpClient`. ## Constructores de comprobantes Puedes armar la [Estructura del comprobante](/v1/guias/emision) con métodos en lugar de escribir el JSON. `ComprobanteBuilder` es opcional. Solo ensambla el request de su tipo (`FacturaRequest`, `NotaCreditoRequest`, etc.) con los valores que le das: no calcula totales, impuestos ni redondeos, y no completa valores por defecto. Tú calculas los importes y la API los calcula y valida igual que si armaras el JSON a mano. No es seguro para uso concurrente, así que crea un constructor por comprobante. ```java import com.ecuafact.sdk.ComprobanteBuilder; import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.RequestOptions; import com.ecuafact.sdk.Tarifa; import com.ecuafact.sdk.contracts.DetalleCompraVenta; import com.ecuafact.sdk.contracts.FacturaRequest; import com.ecuafact.sdk.contracts.Impuesto; import java.math.BigDecimal; import java.time.LocalDate; import java.time.ZoneId; import java.util.List; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); // Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor. ComprobanteBuilder factura = ComprobanteBuilder.factura("0123456789001", "001", "001") .referencias("MiERP", "FACTURA-2026-0002") .fechaEmision(LocalDate.now(ZoneId.of("America/Guayaquil"))) .comprador("07", "9999999999999", "CONSUMIDOR FINAL") .moneda("DOLAR") // Los importes de la linea y de totalConImpuestos los das tu: el SDK no los calcula. .linea(new DetalleCompraVenta("SERV-001", null, "Servicio de prueba", new BigDecimal("1"), new BigDecimal("10.00"), BigDecimal.ZERO, new BigDecimal("10.00"), List.of(new Impuesto("2", "4", new BigDecimal("15"), new BigDecimal("10.00"), new BigDecimal("1.50"))), null)) .totalSinImpuestos(new BigDecimal("10.00")) .totalDescuento(BigDecimal.ZERO) .totalConImpuestos(List.of(new Impuesto("2", "4", new BigDecimal("15"), new BigDecimal("10.00"), new BigDecimal("1.50")))) .propina(BigDecimal.ZERO) .importeTotal(new BigDecimal("11.50")) .pago("01", new BigDecimal("11.50")); FacturaRequest comprobante = factura.construir(); System.out.println("importeTotal " + comprobante.info().importeTotal()); // 11.50 EmisionResultado r = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0002", RequestOptions.create().correlationId("pedido-2026-0458")); System.out.println(r.admission().estado() + " " + r.admission().idOperacion() + " " + r.correlationId()); ``` Deberías ver `importeTotal 11.50` y luego `recibido pedido-2026-0458`. Si ejecutas el programa otro día con la misma `Idempotency-Key`, la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`); en ese caso usa una `Idempotency-Key` y una `referenciaExterna` nuevas. | Tipo | Entrada | Métodos propios | |---|---|---| | Factura (`01`) | `ComprobanteBuilder.factura(ruc, estab, ptoEmi)` | `comprador`, `direccionComprador`, `correo`, `telefono`, `linea`, `ice`, `propina`, `moneda`, `pago` | | Liquidación de compra (`03`) | `ComprobanteBuilder.liquidacionCompra(ruc, estab, ptoEmi)` | `proveedor`, `direccionProveedor`, `linea`, `ice`, `moneda`, `pago` | | Nota de crédito (`04`) | `ComprobanteBuilder.notaCredito(ruc, estab, ptoEmi)` | `comprador`, `docModificado`, `totalDocumentoSustento`, `motivo(razon)`, `linea`, `ice`, `moneda` | | Nota de débito (`05`) | `ComprobanteBuilder.notaDebito(ruc, estab, ptoEmi)` | `comprador`, `docModificado`, `iva(Tarifa)`, `motivo(razon, valor)`, `valorTotal`, `impuestos`, `pago` | | Guía de remisión (`06`) | `ComprobanteBuilder.guiaRemision(ruc, estab, ptoEmi)` | `dirPartida`, `transportista`, `placa`, `fechasTransporte`, `destinatario`, `codEstabDestino`, `ruta`, `docAduaneroUnico`, `bien(codigoInterno, descripcion, cantidad)` | | Retención (`07`) | `ComprobanteBuilder.retencion(ruc, estab, ptoEmi)` | `sujetoRetenido`, `periodoFiscal`, `parteRelacionada`, `docSustento`, `impuestoSustento`, `lineaRetencion`, `pago` | Todos los constructores tienen además `referencias(origen, externa)`, `secuencial`, `fechaEmision` (texto `dd/MM/yyyy` o `LocalDate`), `dirEstablecimiento`, `infoAdicional(nombre, valor)` y `construir()`. Algunos métodos tienen reglas propias: - En `linea(codigo, descripcion, cantidad, precioUnitario, descuento, tarifa)`, `codigo` es el `codigoPrincipal` en la factura y la liquidación, y el `codigoInterno` en la nota de crédito. `descuento` es un importe en dólares y `tarifa` es un `Tarifa.of(codigoPorcentaje, tarifa)`. `linea(DetalleCompraVenta)` (factura y liquidación) y `linea(DetalleNotaCredito)` agregan una línea armada por ti, con sus importes. - `ice(codigoPorcentaje, tarifa)`, `codigoAuxiliar` (no existe en la nota de crédito) y `detalleAdicional(nombre, valor)` se aplican a la última `linea`. - El pago se agrega con `pago(formaPago)`, `pago(formaPago, total)` o `pago(formaPago, total, plazo, unidadTiempo)`. En la retención, los pagos van dentro del documento de sustento. - `bien`, `codEstabDestino`, `ruta` y `docAduaneroUnico` se aplican al último `destinatario(identificacion, razonSocial, direccion, motivoTraslado)`. - `docSustento(codSustento, codDocSustento, numDocSustento, fechaEmisionDocSustento, fechaRegistroContable, numAutDocSustento)` agrega el documento de sustento de la retención; `impuestoSustento`, `lineaRetencion`, `pagoLocExt`, `totalSinImpuestos` e `importeTotal` se aplican a él. `pagoLocExt` no tiene valor por defecto. - Puedes asignar estos totales: `totalSinImpuestos`, `totalDescuento`, `totalConImpuestos`, `importeTotal`, `valorModificacion` (nota de crédito), `valorTotal` e `impuestos` (nota de débito). **El constructor es genérico por tipo.** `ComprobanteBuilder.factura(...)` devuelve `ComprobanteBuilder` y `construir()` devuelve `FacturaRequest`; lo mismo en los demás tipos. Un dato que el tipo no tiene (por ejemplo `proveedor(...)` en una factura) lanza `EcuafactSdkException` al construir, en lugar de descartarse en silencio. **Lo que asignas se envía tal cual.** Todo valor que asignes (subtotal de línea, impuestos, bases, totales, propina, moneda, pagos) se envía exactamente como lo diste, y lo que no asignes no se envía: el constructor no completa totales, impuestos, `propina`, `moneda`, `pagoLocExt` ni el `total` de un pago. Los `BigDecimal` conservan su precisión sin pérdida. | Elemento | Detalle | |---|---| | Tarifa de una línea | `Tarifa.of(codigoPorcentaje, tarifa)` con el `codigoPorcentaje` del [catálogo](/v1/guias/catalogos) y la `tarifa` en porcentaje (`15`, no `0.15`). El SDK envía la pareja tal como la defines. | | Validación | El constructor no valida reglas de negocio ni calcula: solo ayuda a armar el cuerpo. Valida con `client.validar(...)` o emite y lee el 422 de la API, que es la única que calcula y decide. | ## Métodos Esta es la referencia de los métodos de `EcuafactClient`. La identificación que reciben es siempre el valor `identificacion` del contexto. Los métodos que llaman a la API tienen además una sobrecarga con `RequestOptions`, descrita en [Opciones por llamada](#opciones-por-llamada), y todos tienen una variante `*Async`, descrita en [Variantes asíncronas](#variantes-asincronas-y-cancelacion). | Método | Endpoint | Devuelve | |---|---|---| | `getContexto()` | `GET /v1/contexto` | `Contexto` (ver [Contexto y consumo](#contexto-y-consumo)) | | `emitir(comprobante)` / `emitir(comprobante, idempotencyKey)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}` | `EmisionResultado` (ver [Ruta de emisión por tipo de comprobante](#ruta-de-emision-por-tipo-de-comprobante)) | | `emitirEn(identificacion, comprobante)` / `emitirEn(identificacion, comprobante, idempotencyKey)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` | | `validar(comprobante)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionResultado` (ver [Validar sin emitir](#validar-sin-emitir)) | | `validarEn(identificacion, comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionResultado` | | `getOperacion(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation`. `idOperacion` debe ser un UUID. | | `consultarOperacion(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias) | | `esperarResultado(idOperacion)` / `esperarResultado(idOperacion, intervalo, maximo)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída. Opcional; por defecto cada 5 s hasta 120 s. | | `descargarRide(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | `ArchivoComprobante` (PDF) | | `descargarXml(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | `ArchivoComprobante` (XML del comprobante autorizado) | | `getConsumo()` | `GET /v1/consumo` | `QuotaBucket` (ver [Contexto y consumo](#contexto-y-consumo)) | | `listarOperaciones(identificacion, desde, hasta, tipoDocumento, buscar, pagina, tamanoPagina)` | `GET /v1/operaciones` | `PaginaComprobantes` (ver [Listado de operaciones](#listado-de-operaciones)) | | `obtenerSalud()` | `GET /salud` | `boolean`: `true` si el servicio responde. No envía API Key. Ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos). | | `obtenerEstadoServicio()` | `GET /estado` | `EstadoServicio` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)). No envía API Key. | | `listarCatalogos()` | `GET /v1/catalogos` | `Catalogos` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)) | | `obtenerCatalogo(nombre)` | `GET /v1/catalogos/{nombre}` | `CatalogoDetalle` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)) | | `getPerfil(identificacion)` | `GET /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` | | `actualizarPerfil(identificacion, cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` (`cambios` es un `PerfilEmisorUpdate`) | | `actualizarLogo(identificacion, contenido, contentType, nombreArchivo)` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (ver [Logo del perfil](#logo-del-perfil)) | | `consultarContribuyente(identificacion)` / `consultarContribuyente(identificacion, fusionar, fuente)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta`. Sin argumentos extra envía `fusionar=true`. | | `buscarContribuyentes(apellidos)` / `buscarContribuyentes(apellidos, nombres, clase, max)` | `GET /v1/consultas/contribuyentes` | `List` | | `listarEstablecimientos(ruc)` / `listarEstablecimientos(ruc, filtro)` | `GET /v1/consultas/establecimientos/{ruc}` | `EstablecimientosContribuyente` | | `validarIdentificacion(numero)` | `GET /v1/consultas/identificacion/validar/{numero}` | `ValidacionIdentificacion` (revisa `valido()`) | | `decodificarClaveAcceso(claveAcceso)` | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | `ClaveAccesoDecodificada` | | `para(identificacion)` | - (no llama a la API) | `EcuafactContribuyente` (ver [Varios contribuyentes](#varios-contribuyentes)) | | `WebhookEvent.construir(...)` y `WebhookSignature.verify(...)` | - (local) | `WebhookEvent` o `boolean` (ver [Webhooks](#webhooks)) | Ten en cuenta además estos detalles de los métodos y de sus tipos: - Si no configuras `identificacion` en las opciones, `emitir` lanza `EcuafactSdkException`. En ese caso usa la variante que recibe la identificación o la vista `para(...)`. - `ArchivoComprobante` tiene `contenido()` (`byte[]`) y `contentType()`. Las descargas solo existen con el comprobante autorizado; ver [Descargar XML](/v1/guias/consulta-xml). - `PerfilEmisor` y `PerfilEmisorUpdate` son clases con campos públicos (`perfil.razonSocial`), no `record`. ## Importes exactos Todos los importes, cantidades, precios y tarifas son `java.math.BigDecimal` (por ejemplo `InfoFactura.importeTotal()`, `DetalleCompraVenta.precioUnitario()`, `Comprobante.total()`). Un `BigDecimal` creado desde texto guarda `11.50` exacto y el SDK lo envía como número JSON sin notación científica. `Pago.plazo()` es un `BigDecimal` (el contrato lo tipa `number`) que cuenta unidades de `unidadTiempo`; `pago(...)` del constructor acepta también un `Integer`. Crea los importes desde texto, como `new BigDecimal("11.50")`, y nunca desde un `double`, porque `new BigDecimal(11.5)` arrastra el error binario. Después redondea a 2 decimales. ```java import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.math.BigDecimal; import java.math.RoundingMode; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception ObjectMapper mapper = new ObjectMapper().enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS); ObjectNode json = (ObjectNode) mapper.readTree(Files.readString(Path.of("comprobante.json"))); BigDecimal baseImponible = new BigDecimal("10.00"); BigDecimal iva = baseImponible.multiply(new BigDecimal("0.15")).setScale(2, RoundingMode.HALF_UP); // 1.50 ((ObjectNode) json.get("info")).put("totalSinImpuestos", baseImponible); ((ObjectNode) json.get("info")).put("importeTotal", baseImponible.add(iva)); // 11.50 System.out.println(json.get("info").get("importeTotal").decimalValue()); // 11.50 ``` Las reglas de cálculo de cada comprobante están en [Factura](/v1/guias/emision-01). ## Varios contribuyentes Si no configuras `identificacion` en las opciones, pasa la identificación en cada llamada o crea una vista por contribuyente. La vista repite la identificación por ti en cada método. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EcuafactContribuyente; import com.ecuafact.sdk.contracts.PerfilEmisor; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); EcuafactContribuyente matriz = client.para("0123456789001"); PerfilEmisor perfil = matriz.getPerfil(); System.out.println(perfil.razonSocial + " (" + perfil.identificacion + ")"); ``` La vista `EcuafactContribuyente` tiene estos métodos. Los que llaman a la API aceptan además `RequestOptions` al final; en `emitir`, después de `idempotencyKey`. | Método | Equivale a | |---|---| | `identificacion()` | La identificación de la vista. | | `emitir(comprobante)` / `emitir(comprobante, idempotencyKey)` | `client.emitirEn(identificacion, ...)` | | `validar(comprobante)` | `client.validarEn(identificacion, comprobante)` | | `descargarRide(claveAcceso)` | `client.descargarRide(identificacion, claveAcceso)` | | `descargarXml(claveAcceso)` | `client.descargarXml(identificacion, claveAcceso)` | | `getPerfil()` | `client.getPerfil(identificacion)` | | `actualizarPerfil(cambios)` | `client.actualizarPerfil(identificacion, cambios)` | | `actualizarLogo(contenido, contentType, nombreArchivo)` | `client.actualizarLogo(identificacion, ...)` | | `esperarResultado(idOperacion)` / `esperarResultado(idOperacion, intervalo, maximo)` | `client.esperarResultado(...)` | | `getConsumo()` | `client.getConsumo()` (el cupo es de la API Key, no del contribuyente) | ## Logo del perfil Con `actualizarLogo` puedes subir el logo que aparece en el RIDE de tu contribuyente sin armar la petición `multipart/form-data`; recibes el `PerfilEmisor` actualizado. Acepta PNG o JPEG de hasta 512 KB, y `contentType` es obligatorio (`image/png` o `image/jpeg`); si no indicas `nombreArchivo`, el SDK usa `logo`. Un archivo vacío lanza `EcuafactSdkException` sin llamar a la API, y la subida no se reintenta automáticamente. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.PerfilEmisor; import java.nio.file.Files; import java.nio.file.Path; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); byte[] logo = Files.readAllBytes(Path.of("logo.png")); PerfilEmisor perfil = client.actualizarLogo("0123456789001", logo, "image/png", "logo.png"); System.out.println("Logo actualizado para " + perfil.razonSocial + ": " + perfil.logo); ``` Las reglas del archivo y los errores posibles están en [Perfil del emisor](/v1/guias/perfil-emisor). ## Contexto y consumo Antes de emitir puedes preguntar con qué contribuyentes puedes trabajar y cuántos documentos te quedan. `getContexto()` lee el [contexto](/v1/guias/consulta-contexto) de tu API Key y `getConsumo()` lee tu [cupo](/v1/guias/consumo). Ninguna de las dos consume cupo. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.Contexto; import com.ecuafact.sdk.contracts.QuotaBucket; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); Contexto contexto = client.getContexto(); contexto.contribuyentes().forEach(c -> System.out.println(c.identificacion() + " " + c.puedeEmitir() + " " + c.tiposComprobante())); QuotaBucket cupo = client.getConsumo(); System.out.println("Disponibles " + cupo.disponibles() + " de " + cupo.limiteDocumentos() + "; vigente hasta " + cupo.vigenteHasta()); ``` `getContexto()` devuelve un `Contexto`. La `identificacion()` de cada contribuyente es la completa que devuelve el contexto, y es la que va en las rutas y en `infoTributaria.ruc`. | Método | Tipo | Descripción | |---|---|---| | `Contexto.idCliente()` | `String` | Identificador de tu integración. | | `Contexto.nombre()` | `String` | Nombre de tu integración. | | `Contexto.contribuyentes()` | `List` | Contribuyentes habilitados para tu API Key en el ambiente de la URL. | | `Contribuyente.identificacion()` | `String` | Identificación completa del contribuyente; úsala en las rutas. | | `Contribuyente.puedeEmitir()` | `boolean` | `true` si tu API Key puede emitir para este contribuyente. | | `Contribuyente.puedeRecibir()` | `boolean` | `true` si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión. | | `Contribuyente.tiposComprobante()` | `List` | Códigos de los tipos de comprobante habilitados (`01`, `03`, `04`, `05`, `06`, `07`). | | `Contribuyente.marcaBlanca()` | `boolean` | `true` si el contribuyente es un emisor de marca blanca: sus comprobantes no tienen RIDE, y el XML se descarga igual. | `getConsumo()` devuelve un `QuotaBucket`. Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo, y uno cancelado no lo consume. | Método | Tipo | Descripción | |---|---|---| | `limiteDocumentos()` | `int` | Documentos contratados en total: la suma de tus paquetes vigentes. | | `reservados()` | `int` | Documentos de emisiones recibidas que aún no tienen resultado final. | | `consumidos()` | `int` | Documentos descontados por emisiones con resultado final. | | `disponibles()` | `int` | Documentos que aún puedes emitir con tus paquetes vigentes. | | `vigenteHasta()` | `String` | Fecha y hora (ISO 8601, UTC) en que vence el próximo paquete con saldo. | | `limiteExtra()`, `reservadosExtra()`, `consumidosExtra()`, `disponiblesExtra()` | `int` | Se mantienen por compatibilidad y valen 0: todo el saldo está en los cuatro valores anteriores. | El significado de cada valor, con un ejemplo numérico, está en [Consumo y cuotas](/v1/guias/consumo#respuesta). ## Listado de operaciones `listarOperaciones` devuelve una página de los comprobantes de un contribuyente (`GET /v1/operaciones`) y no consume cupo. La `identificacion` es obligatoria; los demás filtros pueden ir en `null`: `desde` y `hasta` en formato `yyyy-MM-dd`, `tipoDocumento` (el código o el nombre del tipo), `buscar` (número, clave de acceso, contraparte o referencia), `pagina` desde 1 y `tamanoPagina` de 1 a 100. Si un filtro no tiene el formato esperado, el SDK lanza `EcuafactSdkException` sin llamar a la API. ```java import com.ecuafact.sdk.contracts.Comprobante; import com.ecuafact.sdk.contracts.PaginaComprobantes; int numero = 1; PaginaComprobantes pagina; do { pagina = client.listarOperaciones("0123456789001", "2026-11-01", "2026-11-30", null, null, numero, 50); for (Comprobante fila : pagina.comprobantes()) { System.out.println(fila.numeroDocumento() + " " + fila.estado() + " " + fila.codEstado() + " " + fila.total()); } numero++; } while (Boolean.TRUE.equals(pagina.hayMas())); ``` La respuesta es un `PaginaComprobantes` con `comprobantes`, `pagina`, `tamanoPagina` y `hayMas`; mientras `hayMas` sea `true`, pide la página siguiente. Cada fila es un `Comprobante` con `claveAcceso`, `numeroDocumento`, `tipoDocumento`, `fechaEmision`, `identificacionContraparte`, `razonSocialContraparte`, `total`, `estado`, `codEstado`, `msgError`, `errores` y `fhAutorizacion`; `estadoOperacion()` y `tipoComprobante()` devuelven los valores tipados. La vista `client.para(identificacion)` ofrece `listarOperaciones` con la identificación fija. ## Estado del servicio y catálogos Puedes consultar el estado público del servicio y los catálogos del SRI sin armar ninguna petición. `obtenerEstadoServicio()` lee el [estado del servicio](/v1/guias/estado-del-servicio) y no envía API Key, así que sirve para comprobar la disponibilidad antes de configurar una credencial o desde tus propias alertas. `listarCatalogos()` y `obtenerCatalogo(nombre)` leen los [catálogos del SRI](/v1/guias/catalogos) con la API Key del cliente. Los catálogos cambian pocas veces al año, así que puedes guardar sus respuestas en caché por una hora. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.EcuafactNotFoundException; import com.ecuafact.sdk.contracts.CatalogoDetalle; import com.ecuafact.sdk.contracts.CatalogoItem; import com.ecuafact.sdk.contracts.Catalogos; import com.ecuafact.sdk.contracts.EstadoServicio; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); EstadoServicio estado = client.obtenerEstadoServicio(); System.out.println(estado.estado() + " " + estado.disponibilidad90Dias()); estado.componentes().forEach(c -> System.out.println(c.nombre() + " " + c.estado())); estado.incidentes().forEach(i -> System.out.println(i.inicio() + " " + i.impacto() + " " + i.titulo() + " " + i.fin())); Catalogos indice = client.listarCatalogos(); indice.catalogos().forEach(c -> System.out.println(c.nombre() + " " + c.descripcion())); try { CatalogoDetalle tarifas = client.obtenerCatalogo("tarifas-iva"); for (CatalogoItem fila : tarifas.items()) { System.out.println(fila.codigo() + " " + fila.descripcion() + " " + fila.valor()); } } catch (EcuafactNotFoundException error) { System.out.println("Ese catálogo no existe"); } ``` Si el catálogo `tarifas-iva` existe, el programa imprime una línea por cada código de IVA con su tarifa. Con una clave que no está en el índice, la API responde 404 con el `codEstado` 3013 (`no_encontrado`) y el SDK lanza `EcuafactNotFoundException`. Los demás errores siguen la jerarquía de [Errores](#errores). Un `nombre` vacío lanza `EcuafactSdkException` sin llamar a la API. ### Estado del servicio `obtenerEstadoServicio()` devuelve un `EstadoServicio`, un `record` con los mismos campos que la [respuesta de la consulta](/v1/guias/estado-del-servicio#respuesta). | Método | Tipo | Descripción | |---|---|---| | `estado()` | `String` | Estado general: `operativo`, `degradado`, `caido` o `sin_datos`. | | `medidoEn()` | `String` | Momento de la última medición (ISO 8601, UTC). `null` si todavía no hay mediciones. | | `componentes()` | `List` | Componentes monitoreados. | | `disponibilidad90Dias()` | `Double` | Porcentaje de minutos sin caída en los últimos 90 días. `null` si aún no hay muestras. | | `incidentes()` | `List` | Incidentes de los últimos 90 días y los que siguen abiertos, del más reciente al más antiguo. | | Método de `ComponenteEstado` | Tipo | Descripción | |---|---|---| | `nombre()` | `String` | Nombre del componente. | | `estado()` | `String` | `operativo`, `degradado`, `caido` o `sin_datos`. | | Método de `IncidentePublico` | Tipo | Descripción | |---|---|---| | `inicio()` | `String` | Inicio del incidente (ISO 8601, UTC). | | `fin()` | `String` | Fin del incidente. `null` mientras sigue abierto. | | `impacto()` | `String` | `degradado` o `caido`. | | `titulo()` | `String` | Título breve. | | `detalle()` | `String` | Qué significó para tus integraciones. `null` si no hay detalle. | Qué hacer ante cada `estado` se explica en [Valores de estado](/v1/guias/estado-del-servicio#valores-de-estado). Para comprobar solo que el servicio responde, `obtenerSalud()` llama a `GET /salud`, que no requiere API Key, y devuelve `true`; si la respuesta no es 2xx, lanza la excepción correspondiente. ### Catálogos `listarCatalogos()` devuelve un `Catalogos` y `obtenerCatalogo(nombre)`, un `CatalogoDetalle`. El `nombre` es la clave que devuelve el índice, como `tarifas-iva`; las claves disponibles están en [Catálogos disponibles](/v1/guias/catalogos#catalogos-disponibles). | Método | Tipo | Descripción | |---|---|---| | `Catalogos.catalogos()` | `List` | Catálogos disponibles, en el orden de la ficha técnica del SRI. | | `CatalogoResumen.nombre()` | `String` | Clave del catálogo; es el valor que recibe `obtenerCatalogo`. | | `CatalogoResumen.descripcion()` | `String` | Descripción breve de lo que contiene. | | `CatalogoDetalle.nombre()` | `String` | Clave del catálogo. | | `CatalogoDetalle.descripcion()` | `String` | Descripción breve del catálogo. | | `CatalogoDetalle.fuente()` | `String` | Tabla o anexo de la ficha técnica del SRI de donde proviene. | | `CatalogoDetalle.items()` | `List` | Filas del catálogo. | | `CatalogoItem.codigo()` | `String` | Código tal como va en el comprobante. Envíalo como texto, con sus ceros a la izquierda cuando los tenga. | | `CatalogoItem.descripcion()` | `String` | Descripción del código. | | `CatalogoItem.valor()` | `BigDecimal` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. `null` si el catálogo no lo tiene. | | `CatalogoItem.vigenteDesde()` | `String` | Primer día de vigencia (`yyyy-MM-dd`). `null` si la fila no está acotada por el inicio. | | `CatalogoItem.vigenteHasta()` | `String` | Último día de vigencia (`yyyy-MM-dd`). `null` si sigue vigente. | | `CatalogoItem.atributos()` | `Map` | Atributos propios del catálogo. `null` si no hay. | ## Consultas SRI Con estos métodos puedes consultar el catastro del SRI, y no consumen cupo. ```java import com.ecuafact.sdk.EcuafactClient; import com.ecuafact.sdk.EcuafactClientOptions; import com.ecuafact.sdk.contracts.BusquedaContribuyente; import com.ecuafact.sdk.contracts.ContribuyenteConsulta; import com.ecuafact.sdk.contracts.EstablecimientosContribuyente; import com.ecuafact.sdk.contracts.ValidacionIdentificacion; import java.util.List; // Dentro de: public static void main(String[] args) throws Exception EcuafactClient client = new EcuafactClient( EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))); ValidacionIdentificacion validacion = client.validarIdentificacion("0123456789001"); ContribuyenteConsulta contribuyente = client.consultarContribuyente("0123456789001"); List encontrados = client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10); EstablecimientosContribuyente establecimientos = client.listarEstablecimientos("0123456789001", "SoloActivos"); System.out.println(validacion.valido() + " " + encontrados.size()); ``` Los parámetros y las respuestas de cada consulta están en [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). ## Siguientes pasos - [Factura](/v1/guias/emision-01): revisa todos los campos y las reglas de cálculo para construir tus comprobantes. - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta qué significa cada `estado` y cada `codEstado`. - [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI sin consultar en bucle. - [Visión general de los SDK](/v1/guias/sdk): compara los cinco SDK y decide entre SDK o HTTP directo. --- # SDK PHP Biblioteca oficial para emitir comprobantes desde PHP 8.2 o superior, seguir su autorización, descargar el RIDE y verificar webhooks. Si desarrollas en PHP, puedes integrarte con nuestros servicios de facturación usando nuestro SDK para PHP. Lo instalas con Composer y, en lugar de armar cada petición con cURL, llamas a métodos como `emitirEn` o `descargarRide`, que reciben y devuelven clases tipadas. Puedes reintentar sin miedo a duplicar comprobantes, porque el SDK reutiliza la `Idempotency-Key` en sus reintentos; además envía tu API Key en cada llamada, te indica si llegaste al límite de solicitudes o si se agotó tu cupo, y verifica la firma de los webhooks que te enviamos. Esta guía sigue el orden de una integración. Primero instalas el paquete, configuras el cliente, emites tu primera factura y sigues su resultado; después recibes webhooks y manejas errores, y al final ajustas los reintentos, las opciones por llamada y la conexión, y armas comprobantes con los constructores. Si todavía no decides entre el SDK y la API por HTTP directo, compáralos en [SDKs](/v1/guias/sdk). > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan > `https://api-sandbox.mynexusapi.com`; cambia a `https://api.mynexusapi.com` > solo cuando emitas comprobantes reales. ## 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: ```text Instala el SDK PHP de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. 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/sdk-php.md antes de escribir código; no inventes campos. Reutiliza el lenguaje, el gestor de paquetes y la estructura del proyecto; si no hay proyecto, crea uno mínimo. Instala con composer require ecuafact/sdk. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Requiere PHP 8.2 o superior con ext-curl. 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 programa e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer. ``` ## Paquete | Dato | Valor | |---|---| | Paquete Composer | [`ecuafact/sdk`](https://packagist.org/packages/ecuafact/sdk) | | Versión | `v1.0.1` | | PHP | 8.2 o superior, con las extensiones `curl` y `json`. | | Dependencias | No necesita otras dependencias fuera de las extensiones. Solo si usas tu propio cliente PSR-18 necesitas `psr/http-client` y `psr/http-factory`. | | Repositorio | [github.com/Ecuanexus/ecuafact-sdk-php](https://github.com/Ecuanexus/ecuafact-sdk-php) | | Cliente | Es síncrono y usa cURL, o tu cliente PSR-18 con `Psr18Transport`. | | Espacio de nombres | `Ecuafact\Sdk` (cliente, opciones, excepciones, webhooks), `Ecuafact\Sdk\Contracts` (clases de datos), `Ecuafact\Sdk\Builders` (constructores). | ## Requisitos - [ ] PHP 8.2 o superior, que compruebas con `php -v`, con la extensión `curl` habilitada (aparece en la lista de `php -m`) y [Composer](https://getcomposer.org/). - [ ] Una API Key de pruebas guardada en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, crea tu sandbox como se explica en [Sandbox de pruebas](/v1/guias/sandbox). - [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier IP. En producción, la IP desde la que ejecutas el código debe estar en **Cuenta > IP permitidas**; si no lo está, la API responde 403 con el `codEstado` 3010 (`ip_no_autorizada`). - [ ] Un [contribuyente](/v1/guias/glosario) con `puedeEmitir` en tu [contexto](/v1/guias/consulta-contexto). El sandbox crea uno con el establecimiento `001` y el punto de emisión `001`. ## Instalación Crea una carpeta para la prueba e instala el paquete. ```bash mkdir ecuafact-prueba && cd ecuafact-prueba composer require ecuafact/sdk ``` Si prefieres fijar la versión exacta, usa `composer require ecuafact/sdk:1.0.1`. Composer crea `vendor/autoload.php`, que incluyes al inicio de cada script con `require __DIR__ . '/vendor/autoload.php';`. Para verificar la instalación, ejecuta este comando. ```bash composer show ecuafact/sdk ``` La instalación funcionó si la salida muestra `versions : * v1.0.1`. ## Configuración Crea el cliente **una vez** por proceso y reutilízalo, porque sirve para todos los contribuyentes de tu API Key. Las opciones se pasan como argumentos con nombre. ```php options()); // la API Key aparece como *** ``` Si no pasas `apiKey`, o pasas `null` o el `false` que devuelve `getenv()` cuando la variable no existe, el SDK lee la variable de entorno `ECUAFACT_API_KEY`; si no pasas `baseAddress`, lee `ECUAFACT_BASE_URL`. Con las dos variables definidas basta `new EcuafactClient(new EcuafactClientOptions())`. Eliges el ambiente con la URL que configuras, porque el SDK no tiene una opción aparte para eso. Usa `https://api-sandbox.mynexusapi.com/` para pruebas y `https://api.mynexusapi.com/` para producción, **sin** `/v1`, ya que el SDK agrega la versión a cada ruta. | Opción | Tipo | Valor por defecto | Descripción | |---|---|---|---| | `baseAddress` | `?string` | `ECUAFACT_BASE_URL` | URL absoluta que debe usar `https`; el SDK rechaza `http` con `EcuafactConfigurationException`. Sin `/v1`, sin consulta (`?`), fragmento (`#`) ni usuario y contraseña. | | `apiKey` | `?string` | `ECUAFACT_API_KEY` | Tu API Key; viaja en la cabecera `X-Api-Key`. No puede tener espacios al inicio o al final ni caracteres de control. Puedes leerla con `$options->apiKey`, que es de solo lectura, y no aparece en `var_dump`, `print_r`, `var_export`, `json_encode` ni en las trazas. | | `identificacion` | `?string` | `null` | Contribuyente por defecto para `emitir` y `validar`. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). | | `validarAntesDeEmitir` | `bool` | `false` | Si es `true`, `emitir` y `emitirEn` llaman antes a `/validar` y solo envían la emisión si la API la da por válida (2 peticiones por emisión). Se explica en [Validar antes de cada emisión](#validar-antes-de-cada-emision). | | `timeout` | `float` | `30.0` | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta, en segundos, con fracciones. Debe ser mayor que 0 y solo se aplica con el transporte cURL. | | `userAgent` | `string` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. Sin caracteres de control. | | `retryTransientFailures` | `bool` | `true` | Reintenta fallos transitorios (ver [Reintentos](#idempotencia-y-reintentos)). `false` desactiva todo reintento. | | `maxAttempts` | `int` | `3` | Intentos por solicitud, incluido el primero. Debe ser 1 o mayor. | | `transport` | `?TransportInterface` | `null` (cURL) | Transporte HTTP propio, por ejemplo `Transport\Psr18Transport` para usar tu cliente PSR-18 (ver [Conexión](#conexion-proxy-tls-y-psr-18)). | | `respectRetryAfter` | `bool` | `true` | Espera lo que indique la cabecera `Retry-After` antes de reintentar, si es mayor que la espera calculada. | | `maxRetryDelaySeconds` | `float` | `60.0` | Espera máxima entre reintentos, en segundos. Con `0` no hay tope. | | `retryRateLimited` | `bool` | `true` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`), respetando `Retry-After` y `maxRetryDelaySeconds`. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. | | `retryableStatusCodes` | `?int[]` | `null` = `[408, 425, 500, 502, 503, 504]` | Estados HTTP que se reintentan (enteros entre 100 y 599). El 429 no va aquí: lo controla `retryRateLimited`. Los valores por defecto están en `EcuafactClientOptions::DEFAULT_RETRYABLE_STATUS_CODES`. | | `retryBaseDelaySeconds` | `float` | `0.2` | Espera base entre reintentos, en segundos. | | `retryBackoff` | `RetryBackoff\|string` | `RetryBackoff::Linear` | `Linear`: base x intento (0.2, 0.4, 0.6 s). `Exponential`: base x 2^(intento-1) (0.2, 0.4, 0.8 s). Acepta también `'linear'` o `'exponential'`. | | `retryJitterSeconds` | `float` | `0.05` | Variación aleatoria que se suma a cada espera, en segundos (ver [Reintentos](#idempotencia-y-reintentos)). | | `totalTimeoutSeconds` | `?float` | `null` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas, en segundos. Al superarlo lanza `EcuafactTimeoutException`. Mayor que 0. | | `connectTimeout` | `?float` | `null` | Tiempo máximo para abrir la conexión, en segundos. Mayor que 0. Solo con el transporte cURL. | | `proxy` | `?string` | `null` | Proxy, por ejemplo `http://proxy.miempresa.local:8080`. Aparece como `***` en `var_dump`. Solo con el transporte cURL. | | `caInfo` | `?string` | `null` | Ruta a un bundle de CA propio (CA corporativa). Solo con el transporte cURL. | | `verifyPeer` | `bool` | `true` | Verificación del certificado TLS. Déjalo en `true` fuera de pruebas locales. Solo con el transporte cURL. | | `curlOptions` | `array` | `[]` | Opciones `CURLOPT_*` adicionales. Solo con el transporte cURL. | | `maxResponseBytes` | `?int` | 32 MiB (`33554432`); 100 MiB (`104857600`) en las descargas de RIDE y XML | Tope en bytes del cuerpo de una respuesta. Un entero positivo lo aplica a todas las llamadas, incluidas las descargas; `null` o `0` lo desactiva. Al superarlo lanza `EcuafactResponseTooLargeException` con `$limite` y `$bytesLeidos`. | | `additionalInfo` | `?string` | `null` | Valor de la cabecera `X-Additional-Info` en todas las solicitudes, por ejemplo `erp=MiERP/4.2; sucursal=quito`; no se guarda con el comprobante. Con `null` o `''` no se envía la cabecera. Sus reglas están en [Información adicional](#informacion-adicional). | ```php new EcuafactClientOptions(maxResponseBytes: 64 * 1024 * 1024); // 64 MiB; null desactiva el tope ``` Las opciones se validan al crearlas. `EcuafactClientOptions` lanza `EcuafactConfigurationException`, antes de hacer cualquier llamada, en cualquiera de estos casos: - Falta la API Key o la URL. - La URL no es válida o termina en `/v1`. - La API Key tiene espacios o caracteres de control. - `timeout` no es mayor que 0, o `maxAttempts` es menor que 1. - Un tiempo es negativo. - `maxResponseBytes` es negativo. - `retryBackoff` no es `linear` ni `exponential`. - `additionalInfo` tiene caracteres fuera de ASCII imprimible, espacios al inicio o al final o más de 256 caracteres. El mensaje de la excepción nunca incluye la API Key. ## Quickstart: de la API Key al RIDE Este script hace el flujo completo en el ambiente de pruebas: lee tu [contexto](/v1/guias/consulta-contexto), emite una factura, espera el resultado del SRI con el [seguimiento](/v1/guias/consulta-operacion) y descarga el [RIDE](/v1/guias/glosario), el PDF del comprobante. ### Paso 1. Guarda el comprobante Guarda este JSON como `comprobante.json` junto al script. Es una factura a consumidor final, con el tipo de identificación `07` y la identificación `9999999999999`, que solo se admite en facturas de hasta 50.00. Factura 10.00 más el IVA del 15 %, que son 1.50, por un total de 11.50. No lleva `secuencial`, porque te asignamos el siguiente [secuencial](/v1/guias/glosario) de la serie `estab`-`ptoEmi`. El script reemplaza `ruc` por el de tu contexto y `fechaEmision` por la fecha de hoy. ```json { "origenReferencia": "MiERP", "referenciaExterna": "FACTURA-2026-0001", "infoTributaria": { "ruc": "0123456789001", "estab": "001", "ptoEmi": "001" }, "info": { "fechaEmision": "07/10/2026", "tipoIdentificacionComprador": "07", "identificacionComprador": "9999999999999", "razonSocialComprador": "CONSUMIDOR FINAL", "totalSinImpuestos": 10.00, "totalDescuento": 0.00, "totalConImpuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "baseImponible": 10.00, "valor": 1.50 } ], "propina": 0.00, "importeTotal": 11.50, "moneda": "DOLAR", "pagos": [ { "formaPago": "01", "total": 11.50 } ] }, "detalles": [ { "codigoPrincipal": "SERV-001", "descripcion": "Servicio de prueba", "cantidad": 1, "precioUnitario": 10.00, "descuento": 0.00, "precioTotalSinImpuesto": 10.00, "impuestos": [ { "codigo": "2", "codigoPorcentaje": "4", "tarifa": 15, "baseImponible": 10.00, "valor": 1.50 } ] } ] } ``` > [!NOTE] > El JSON no lleva el tipo del comprobante: lo da la clase que lo recibe (`FacturaRequest` en este caso), como se explica en [Tipo de comprobante y ruta](#tipo-de-comprobante-y-ruta). `estab` y `ptoEmi` deben ser un [establecimiento](/v1/guias/glosario) y un [punto de emisión](/v1/guias/glosario) de tu emisor; el sandbox crea el establecimiento `001` con el punto de emisión `001`. Cada campo está explicado en [Factura](/v1/guias/emision-01). ### Paso 2. Escribe el script Guarda el código siguiente como `quickstart.php`. `Hydrator::hydrate` convierte el JSON en las clases del SDK (`FacturaRequest`, `InfoFactura`, `DetalleCompraVenta`...); también puedes construir esos objetos propiedad por propiedad o con los [constructores](#constructores-de-comprobantes). `Hydrator` ignora las propiedades del JSON que no existen en las clases del SDK. El SDK usa la clase del comprobante para elegir la ruta. El paso 4 usa `esperarResultado`, un método **opcional** que consulta la operación cada 5 segundos hasta tener un resultado final o hasta 2 minutos. En producción puedes usar en cambio el flujo asíncrono, en el que emites, guardas el `idOperacion` y procesas el resultado cuando llega el [webhook](/v1/guias/webhooks); así tu proceso no se queda esperando. ```php getContexto(); $emisor = null; foreach ($contexto->contribuyentes ?? [] as $contribuyente) { if ($contribuyente->puedeEmitir) { $emisor = $contribuyente; break; } } if ($emisor === null) { exit('Tu API Key no tiene un contribuyente habilitado para emitir.' . PHP_EOL); } echo "Emisor {$emisor->identificacion}" . PHP_EOL; // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador). /** @var FacturaRequest $comprobante */ $comprobante = Hydrator::hydrate(FacturaRequest::class, json_decode(file_get_contents('comprobante.json'))); $comprobante->infoTributaria->ruc = $emisor->identificacion; $comprobante->info->fechaEmision = (new DateTimeImmutable('now', new DateTimeZone('America/Guayaquil')))->format('d/m/Y'); // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key. $emision = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001'); $idOperacion = $emision->admission->idOperacion; // codEstado es 1001 (aun sin clave de acceso) o 1002 (con claveAcceso); acepta los dos. echo "estado {$emision->admission->estado} codEstado {$emision->admission->codEstado} idOperacion {$idOperacion}" . PHP_EOL; // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min). $operacion = $client->esperarResultado($idOperacion); echo "estado {$operacion->estado} codEstado {$operacion->codEstado}" . PHP_EOL; foreach ($operacion->errores ?? [] as $detalle) { echo " - {$detalle}" . PHP_EOL; } // 5. RIDE: solo existe cuando el comprobante esta autorizado. if ($operacion->esAutorizado()) { $ride = $client->descargarRide($emisor->identificacion, $operacion->claveAcceso); file_put_contents('ride.pdf', $ride->contenido); echo "RIDE guardado en ride.pdf; claveAcceso {$operacion->claveAcceso}" . PHP_EOL; } elseif (!$operacion->esFinal()) { echo 'Aun sin resultado: consulta mas tarde o espera el webhook.' . PHP_EOL; } } catch (EcuafactApiException $error) { echo "HTTP {$error->estadoHttp} codEstado {$error->codEstado}: {$error->msgError}" . PHP_EOL; foreach ($error->errores as $detalle) { echo " - {$detalle}" . PHP_EOL; } echo "X-Correlation-Id: {$error->correlationId}" . PHP_EOL; } ``` ### Paso 3. Ejecuta y verifica ```bash php quickstart.php ``` Deberías ver algo como esto; los identificadores cambian en cada ejecución: ``` Emisor 0123456789001 estado recibido codEstado 1001 idOperacion 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f estado autorizado codEstado 2001 RIDE guardado en ride.pdf; claveAcceso 0710202601012345678900110010010000001231234567811 ``` El programa funcionó si ves `estado autorizado` y el ejemplo guardó el RIDE como `ride.pdf`. La tabla explica cada línea que puede imprimir. | Salida | Significado | Qué hacer | |---|---|---| | `estado recibido codEstado 1001` | La API aceptó la emisión y respondió `202 Accepted`. Todavía no es la autorización. La respuesta puede traer 1001, cuando aún no hay clave de acceso y `claveAcceso` es `null`, o 1002, cuando ya la trae; tu código debe aceptar los dos. Si repetiste la misma `Idempotency-Key` con el mismo cuerpo, recibes la misma operación. | Sigue con el seguimiento. Para emitir otra factura cambia `referenciaExterna` y la `Idempotency-Key`. | | `estado autorizado codEstado 2001` | El SRI autorizó el comprobante; `claveAcceso` trae la [clave de acceso](/v1/guias/glosario) de 49 dígitos. | Descarga el RIDE o el XML. | | `estado rechazado codEstado 3001` | El SRI rechazó el comprobante. Es un rechazo fiscal, y las líneas que empiezan con `-` muestran el mensaje del SRI, que llega en `errores`. | Corrige los datos y emite un comprobante nuevo con **nueva** `Idempotency-Key`, nueva `referenciaExterna` y un secuencial nuevo. | | `estado rechazado codEstado 3002`, `rechazo_configuracion` o `error` | El comprobante no se emitió por su contenido, por la configuración del emisor o por un fallo. | Sigue la fila de su `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion). | | `estado cancelado codEstado 6001` | La plataforma canceló el envío; no se emitió y no consumió cupo. | Emite de nuevo con una **nueva** `Idempotency-Key`. | | `Aun sin resultado` | Pasaron 2 minutos y el `estado` sigue en `recibido`. | Vuelve a consultar más tarde o espera el [webhook](/v1/guias/webhooks). No emitas de nuevo. | | `HTTP 401 codEstado 3009` | La API Key no es válida. | Revisa `ECUAFACT_API_KEY`. | | `HTTP 403 codEstado 3011` | El contribuyente o el tipo de comprobante no está habilitado, o `ruc` no coincide con el contribuyente de la ruta. | Revisa `puedeEmitir` y `tiposComprobante` en el contexto. | | `HTTP 422 codEstado 3002` | Falta un campo, un campo está mal formado o no se cumple una regla fiscal. Lee las líneas que empiezan con `-`. | Corrige el JSON; un 422 consume 1 documento como intento. | > [!NOTE] > Si ejecutas el script otro día con la misma `Idempotency-Key`, la fecha cambia > el cuerpo y la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Usa una > `Idempotency-Key` y una `referenciaExterna` nuevas para cada factura nueva. ## Tipo de comprobante y ruta Así como la API tiene un endpoint por tipo de documento, el SDK tiene una clase de solicitud por tipo, y esa clase elige la ruta de emisión y de validación. Pasas la clase a `emitir`, `emitirEn`, `validar` o `validarEn` y el SDK llama al endpoint de su tipo; no hay campo de tipo en el cuerpo ni argumento de tipo en la llamada. ```php $emision = $client->emitirEn($identificacion, $factura, 'FACTURA-2026-0001'); // $factura es un FacturaRequest $validacion = $client->validarEn($identificacion, $notaCredito); // $notaCredito es un NotaCreditoRequest ``` Cada clase tiene solo las propiedades de su esquema del contrato, con los mismos nombres y tipos. En el docblock de cada propiedad, `Obligatorio.` marca las que el contrato exige; el SDK no las valida, la API responde con un 422 y su detalle. Las clases comunes se reutilizan en todos los tipos. | Clase de solicitud | Cabecera | Líneas | Comunes | |---|---|---|---| | `FacturaRequest` | `InfoFactura` (incluye la exportación) | `DetalleCompraVenta` | `InfoTributaria`, `Pago`, `Impuesto`, `CampoAdicional` | | `LiquidacionCompraRequest` | `InfoLiquidacionCompra` | `DetalleCompraVenta` | `InfoTributaria`, `Pago`, `Impuesto`, `CampoAdicional` | | `NotaCreditoRequest` | `InfoNotaCredito` | `DetalleNotaCredito` | `InfoTributaria`, `Impuesto`, `CampoAdicional` | | `NotaDebitoRequest` | `InfoNotaDebito` | `Motivo` | `InfoTributaria`, `Pago`, `Impuesto`, `CampoAdicional` | | `GuiaRemisionRequest` | `InfoGuiaRemision` | `Destinatario` con `DetalleGuia` | `InfoTributaria`, `CampoAdicional` | | `RetencionRequest` | `InfoComprobanteRetencion` | `DocsSustento` con `ImpuestoDocSustento` y `RetencionLinea` | `InfoTributaria`, `Pago`, `CampoAdicional` | Todas implementan `SolicitudComprobante`, que expone `tipoComprobante()` (un `TipoComprobante`), útil si guardas solicitudes de varios tipos en una misma lista. `EcuafactTipoComprobanteException` solo se lanza cuando el filtro `tipoDocumento` de `listarOperaciones` no es uno de los seis tipos. | Código | Documento | Ruta de emisión | Ruta de validación | |---|---|---|---| | `01` | Factura | `POST /v1/contribuyentes/{identificacion}/facturas` | `POST .../facturas/validar` | | `03` | Liquidación de compra | `POST .../liquidaciones-compra` | `POST .../liquidaciones-compra/validar` | | `04` | Nota de crédito | `POST .../notas-credito` | `POST .../notas-credito/validar` | | `05` | Nota de débito | `POST .../notas-debito` | `POST .../notas-debito/validar` | | `06` | Guía de remisión | `POST .../guias-remision` | `POST .../guias-remision/validar` | | `07` | Comprobante de retención | `POST .../retenciones` | `POST .../retenciones/validar` | `emitir`, `emitirEn`, `validar` y `validarEn` eligen la ruta por ti y no cambian su firma. Las rutas de seguimiento, consulta, descarga y correo no cambian. ## Validar sin emitir Las reglas de negocio de los comprobantes (campos requeridos, formatos de `estab`, `ptoEmi` y `secuencial`, catálogos, topes, coherencia aritmética) viven solo en la API. El SDK no las revisa: `validar` siempre llama a `/validar`, y `emitir` envía el comprobante directo y lanza `EcuafactValidationException` con el 422 de la API. Así, cuando la API cambia una regla no tienes que actualizar el SDK. Antes de emitir puedes comprobar que un comprobante cumple las reglas de la emisión con `validar`, o con `validarEn` si indicas la identificación del contribuyente. La validación usa la ruta del tipo y le agrega `/validar`; por ejemplo, una nota de crédito (`04`) se valida en `POST .../notas-credito/validar`. La validación no emite nada ni consume cupo, y no necesita `Idempotency-Key`; el SDK no la envía. El detalle de qué se valida está en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). El método devuelve un `ValidacionResultado` con `valido`, `codEstado`, `msgError`, `errores`, `advertencias` y `correlationId`. Cuando el comprobante cumple las reglas, la API responde 200, `valido` es `true`, `codEstado` y `msgError` son `null` y `errores` llega vacío. `advertencias` trae los avisos que la API devuelve junto al resultado (por ejemplo, que ignora la firma de un XML que la trae); un aviso no impide emitir. Cuando el comprobante no cumple una regla, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`) y el SDK no lanza una excepción: recibes `valido` en `false` y los problemas en `errores`, para que los corrijas antes de emitir. ```php $validacion = $client->validarEn($emisor->identificacion, $comprobante); if ($validacion->valido) { $emision = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001'); } else { foreach ($validacion->errores as $detalle) { echo " - {$detalle}" . PHP_EOL; } } ``` Cualquier otra respuesta de error lanza la misma excepción que en la emisión. Por ejemplo, si el contribuyente o el tipo de comprobante no están habilitados para tu API Key, recibes `EcuafactAuthException` con el `codEstado` 3011 (`acceso_denegado`). Como validar no tiene efectos, el SDK repite la llamada ante fallos de red o errores temporales del servidor igual que en una consulta. Un comprobante válido todavía puede fallar al emitirse por cupo o porque ya lo emitiste. ### Validar antes de cada emisión Si quieres que cada emisión pase primero por `/validar`, activa `validarAntesDeEmitir: true` en `EcuafactClientOptions`, o `validarAntes: true` en `RequestOptions` para una sola llamada (la opción de la llamada reemplaza a la del cliente). Con la opción activa, `emitir` y `emitirEn` llaman primero a `/validar`: - Si `valido` es `false` o hay `errores`, lanzan `EcuafactValidationException` (HTTP 422, `codEstado` 3002) con esos `errores`, y la emisión no se envía. - Si es válido, envían la emisión y las `advertencias` quedan en `EmisionResultado::$advertencias`. Una advertencia no bloquea. Por defecto es `false`, porque duplica las peticiones: sin la opción, una emisión hace 1 petición; con ella, 2. ```php $client = new EcuafactClient(new EcuafactClientOptions( apiKey: getenv('ECUAFACT_API_KEY'), validarAntesDeEmitir: true, )); $resultado = $client->emitirEn($emisor->identificacion, $comprobante, 'FACTURA-2026-0001'); foreach ($resultado->advertencias as $aviso) { echo "Aviso: {$aviso}" . PHP_EOL; } ``` ## Seguimiento del resultado La emisión responde `202 Accepted` en cuanto la API recibe el comprobante, y el resultado del SRI llega después. Puedes conocerlo de tres formas. | Forma | Método | Cuándo usarla | |---|---|---| | Esperar en tu proceso | `esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0, $opciones = null)` | La usas en scripts, pruebas y procesos que pueden esperar unos segundos. | | Consultar una vez | `getOperacion($idOperacion, $opciones = null)` (alias: `consultarOperacion`) | La usas en tareas programadas que revisan operaciones pendientes, o para mostrar el estado cuando un usuario lo pide. | | Recibirlo | [Webhooks](#webhooks) | En producción, te avisamos sin que consultes. | `esperarResultado` consulta `GET /v1/operaciones/{idOperacion}` cada `$intervalo` segundos hasta que `esFinal()` sea `true` o hasta que pasen `$maximo` segundos, y devuelve la **última** operación leída, así que revisa `esFinal()` antes de decidir. Los tiempos se expresan en segundos (`float`), y un valor negativo lanza `EcuafactSdkException`. Cada consulta cuenta para tu límite de solicitudes por minuto. `$opciones` se aplica a cada consulta. `getOperacion`, `consultarOperacion` y `esperarResultado` exigen que `$idOperacion` sea un UUID; si no lo es, lanzan `EcuafactSdkException` sin llamar a la API. ```php esperarResultado('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f', 3.0, 60.0); if ($operacion->esAutorizado()) { echo "Autorizado: {$operacion->claveAcceso}" . PHP_EOL; } elseif ($operacion->esFinal()) { echo "Final sin autorizacion: estado {$operacion->estado}, codEstado {$operacion->codEstado}: {$operacion->msgError}" . PHP_EOL; foreach ($operacion->errores ?? [] as $detalle) { echo " - {$detalle}" . PHP_EOL; } } else { echo "Aun sin resultado ({$operacion->estado}); vuelve a consultar con getOperacion mas tarde." . PHP_EOL; } ``` Reemplaza el `idOperacion` del ejemplo por el que recibiste al emitir. `Operation` tiene estas propiedades, y todas pueden ser `null`: | Propiedad | Tipo | Descripción | |---|---|---| | `estado` | `?string` | `recibido`, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Solo `recibido` no es final. | | `codEstado` | `?int` | Código numérico del resultado; su primer dígito es el `estado`. En `recibido` es 1001, sin clave de acceso, o 1002, con `claveAcceso`; en `autorizado`, 2001; y cuando no se autorizó, el código de la causa, por ejemplo 3001 (`rechazo_sri`) o 4002 (`firma_no_valida`). Compáralo con las constantes de `CodEstado`. | | `msgError` | `?string` | Descripción general y fija del código; `null` con `recibido` y `autorizado`. | | `errores` | `?array` | Lista de textos con el detalle del resultado; en un rechazo del SRI trae su mensaje. La API la envía siempre, vacía si no hay detalle. | | `idOperacion` | `?string` | UUID de la operación. | | `urlEstado` | `?string` | URL completa del seguimiento. | | `ambiente` | `?int` | `1` = pruebas, `2` = producción. | | `tipoDocumento` | `?string` | Tipo de comprobante (`01` a `07`). | | `numeroDocumento` | `?string` | Número del comprobante, por ejemplo `001-001-000000123`. | | `referenciaExterna` | `?string` | La `referenciaExterna` que enviaste al emitir. | | `claveAcceso` | `?string` | Clave de acceso de 49 dígitos; es `null` con el `codEstado` 1001. | | `fhRecibido` | `?string` | Momento en que la API aceptó la emisión (ISO 8601 con zona horaria). | | `fhAutorizacion` | `?string` | Momento de la autorización del SRI, cuando existe. No la uses para decidir; decide con `estado`. | Como todos los modelos de respuesta, `Operation` tiene además la propiedad `extra` (`array`), que guarda los campos que la API devuelve y el modelo no declara, con su nombre como clave y los objetos JSON como arreglos asociativos. Está vacía (`[]`) cuando no hay campos nuevos y no se envía a la API si serializas el modelo. El significado de cada `estado` y de cada `codEstado` está en [Seguimiento de una operación](/v1/guias/consulta-operacion#que-hacer-segun-el-estado). ## Estados tipados `Operation`, `Admission` y `Comprobante` conservan las propiedades de la API (`estado`, `codEstado`, `tipoDocumento`) y agregan métodos que devuelven enums de PHP. Un valor que el SDK no conoce no rompe tu código, porque se lee como `Desconocido`, o como `null` en `tipoComprobante()`, y el texto original sigue en la propiedad. | Método | Enum | Casos | |---|---|---| | `$operacion->estadoOperacion()`, `$comprobante->estadoOperacion()` | `Contracts\EstadoOperacion` | `Recibido`, `Autorizado`, `Rechazado`, `RechazoConfiguracion`, `Error`, `Cancelado`, `Desconocido` | | `$operacion->tipoComprobante()`, `$comprobante->tipoComprobante()` | `?Contracts\TipoComprobante` | `Factura` (`01`), `LiquidacionCompra` (`03`), `NotaCredito` (`04`), `NotaDebito` (`05`), `GuiaRemision` (`06`), `Retencion` (`07`); `null` si el código no se conoce | | `$operacion->esFinal()` | `bool` | `true` si `estado` es cualquier valor distinto de `recibido`. | | `$operacion->esAutorizado()` | `bool` | `true` si `estado` es `autorizado`. | | `$evento->eventType` | `Contracts\TipoEventoWebhook` | `DocumentoAutorizado`, `DocumentoRechazado`, `DocumentoFallido`, `OperacionRequiereAtencion`, `Desconocido` | Los valores de `codEstado` están como constantes `int` en `Contracts\CodEstado`, con el nombre de cada código del [catálogo](/v1/guias/errores#catalogo-de-codestado) en mayúsculas, por ejemplo `CodEstado::RECHAZO_SRI` (3001), `CodEstado::COMPROBANTE_INVALIDO` (3002) o `CodEstado::LIMITE_SOLICITUDES` (5005). `CodEstado::estado($codigo)` devuelve el `EstadoOperacion` que corresponde al primer dígito, incluso para un código que tu versión del SDK todavía no conoce, y `CodEstado::nombre($codigo)` devuelve su nombre. ```php getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'); echo match (true) { $operacion->estadoOperacion() === EstadoOperacion::Autorizado => 'Descarga el RIDE', $operacion->estadoOperacion() === EstadoOperacion::Recibido => 'Consulta mas tarde', $operacion->codEstado === CodEstado::RECHAZO_SRI => 'Corrige y emite un comprobante nuevo: ' . implode(' | ', $operacion->errores ?? []), $operacion->estadoOperacion() === EstadoOperacion::Rechazado => "Corrige segun codEstado {$operacion->codEstado}: {$operacion->msgError}", $operacion->estadoOperacion() === EstadoOperacion::Cancelado => 'Emite de nuevo con nueva Idempotency-Key', default => 'Consulta mas tarde', } . PHP_EOL; ``` ## Webhooks Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle y, antes de procesar cada entrega, comprobar que te la enviamos nosotros. El SDK te ayuda a recibir webhooks: verifica la firma y te entrega el evento tipado, pero no administra los destinos. Los destinos (la URL a la que enviamos cada evento, sus eventos suscritos y su secreto) los administras desde el Portal del Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP o con la API REST, como se explica en [Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api). `WebhookEvent::construir` verifica la cabecera `Ecuafact-Signature` (`t=,v1=`) contra el cuerpo **crudo** y, si es válida, devuelve el evento tipado. Si la firma no coincide, está fuera de la tolerancia (300 s por defecto, `WebhookSignature::DEFAULT_TOLERANCE_SECONDS`) o el cuerpo no es un objeto JSON, lanza `EcuafactWebhookException`. | Método | Devuelve | Lanza | |---|---|---| | `WebhookEvent::construir($secretos, $cabecera, $cuerpo, $toleranceSeconds = 300, $now = null)` | `WebhookEvent` | `EcuafactWebhookException` | | `WebhookSignature::construirEvento(...)` | Lo mismo que `construir`, con los mismos argumentos. | `EcuafactWebhookException` | | `WebhookSignature::verify($secretos, $cabecera, $cuerpo, $now = null, $toleranceSeconds = 300)` | `bool` | Nunca. | | `WebhookSignature::sign($secreto, $unixSeconds, $cuerpo)` | La cabecera `t=...,v1=...` | Nunca. Útil para probar tu endpoint en local. | `$secretos` acepta un secreto (`string`) o un arreglo de secretos, y la entrega es válida si coincide con cualquiera; así puedes rotar el secreto sin rechazar entregas. Agrega el nuevo, publica tu aplicación y quita el anterior cuando las entregas lleguen firmadas con el nuevo, como se explica en [Rotación de secreto](/v1/guias/webhooks-firma#rotacion-de-secreto). Pasa siempre un `string` o un arreglo, porque `getenv()` devuelve `false` si la variable no existe y `false` no es un argumento válido. El ejemplo siguiente usa PHP sin framework. Guarda tu secreto en `ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en `ECUAFACT_WEBHOOK_SECRET_ANTERIOR`. ```php eventTypeRaw . '|' . $evento->resourceId); if (file_exists($marca)) { http_response_code(200); // Duplicado: ya procesado. exit; } touch($marca); match ($evento->eventType) { TipoEventoWebhook::DocumentoAutorizado => error_log("Autorizado {$evento->idOperacion} {$evento->claveAcceso}"), TipoEventoWebhook::DocumentoRechazado => error_log("Rechazo fiscal {$evento->idOperacion}: codEstado {$evento->codEstado} " . implode(' | ', $evento->errores)), TipoEventoWebhook::DocumentoFallido => error_log("No emitido {$evento->idOperacion}: estado {$evento->estado}, codEstado {$evento->codEstado}"), default => error_log("Evento {$evento->eventTypeRaw} prueba=" . var_export($evento->probe, true)), }; http_response_code(200); ``` Para probarlo en local, firma un cuerpo con `WebhookSignature::sign` y envíalo con cURL. ```php [!WARNING] > Verifica la firma sobre el cuerpo crudo (`php://input`). En Laravel usa > `$request->getContent()`; no uses `$request->all()` ni vuelvas a codificar el > JSON. ### Standard Webhooks Cada entrega trae además las cabeceras del estándar [Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks) (`webhook-id`, `webhook-timestamp` y `webhook-signature`), firmadas con el mismo secreto. Con el SDK puedes verificar cualquiera de las dos firmas, sin decidir cuál llegó. | Método | Qué hace | |---|---| | `WebhookEvent::construirDesdeCabeceras($secretos, $cabeceras, $cuerpo, $toleranceSeconds = 300, $now = null)` | Devuelve el `WebhookEvent` si `Ecuafact-Signature` o Standard Webhooks es válida; si no, lanza `EcuafactWebhookException`. | | `WebhookSignature::construirEventoDesdeCabeceras(...)` | Lo mismo que el anterior, con los mismos argumentos. | | `WebhookSignature::verificarCabeceras($secretos, $cabeceras, $cuerpo, $now = null, $toleranceSeconds = 300)` | Devuelve `bool` con la misma regla y nunca lanza una excepción. | | `WebhookSignature::verificarStandardWebhooks($secretos, $webhookId, $webhookTimestamp, $webhookSignature, $cuerpo, $now = null, $toleranceSeconds = 300)` | Devuelve `bool`. Verifica solo la firma de Standard Webhooks. | | `WebhookSignature::firmarStandardWebhooks($secreto, $webhookId, $unixSeconds, $cuerpo)` | Devuelve el valor de `webhook-signature` (`v1,`). Sirve para pruebas automatizadas. | `$cabeceras` es un arreglo asociativo cuyos nombres no distinguen mayúsculas, así que sirven `getallheaders()`, las cabeceras de una petición PSR-7 o `$_SERVER`. El secreto puede llevar o no el prefijo `whsec_`, y también aceptas un arreglo de secretos para la rotación. Con `construirDesdeCabeceras` verificas `Ecuafact-Signature` si viene y, si no viene o no es válida, Standard Webhooks. ```php try { $evento = WebhookEvent::construirDesdeCabeceras($secretos, getallheaders(), $cuerpoCrudo); } catch (EcuafactWebhookException) { http_response_code(401); exit; } ``` Los eventos y su contenido están en [Webhooks](/v1/guias/webhooks), y el algoritmo de la firma, en [Verificación de firma](/v1/guias/webhooks-firma). ## Errores Todas las excepciones del SDK heredan de `EcuafactSdkException`, que extiende `\RuntimeException`, y las que vienen de una respuesta de la API heredan además de `EcuafactApiException`. Captura primero las específicas y al final las generales. Todas están en el espacio de nombres `Ecuafact\Sdk`. | Excepción | Hereda de | Cuándo ocurre | Qué hacer | |---|---|---|---| | `EcuafactConfigurationException` | `EcuafactSdkException` | Falta la API Key o la URL, la URL no es válida o termina en `/v1`, la API Key tiene espacios o caracteres de control, o una opción del cliente o de `RequestOptions` es inválida. | Corrige la configuración. No llama a la API. | | `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API tras agotar los intentos. Trae `curlErrno` cuando el error viene de cURL, `idempotencyKey` y `correlationId`. | Reintenta más tarde con la misma `idempotencyKey`. | | `EcuafactTimeoutException` | `EcuafactSdkException` | Se agotó `timeout` en el último intento o el tope total de la llamada. Trae `idempotencyKey` y `correlationId`. | Si emitías, consulta antes el seguimiento o reintenta con la misma `idempotencyKey`. | | `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida, o cuerpo que no es un objeto JSON. | Responde 401 y no proceses el evento. | | `EcuafactAuthException` | `EcuafactApiException` | HTTP 401 o 403, con el `codEstado` 3009 (`credenciales_invalidas`), 3010 (`ip_no_autorizada`) o 3011 (`acceso_denegado`). | Corrige la API Key, registra la IP o revisa que el contribuyente y el tipo estén habilitados. | | `EcuafactValidationException` | `EcuafactApiException` | HTTP 400, 413, 415, 422 o 501: solicitud rechazada, con el `codEstado` 3002 (`comprobante_invalido`), 3003 (`solicitud_invalida`), 3006 (`cuerpo_excedido`), 3007 (`version_no_soportada`), 3008 (`no_implementado`) o 3012 (`filtros_invalidos`). | Corrige según `errores`. Un 422 con el `codEstado` 3002 no consume cupo, porque el comprobante no llegó a emitirse. | | `EcuafactNotFoundException` | `EcuafactApiException` | HTTP 404, con el `codEstado` 3013 (`no_encontrado`), o con `codEstado` en 0 si la ruta no existe y la respuesta no trae cuerpo de error. | Verifica el `idOperacion`, la `claveAcceso` o el ambiente (URL). | | `EcuafactConflictException` | `EcuafactApiException` | HTTP 409, con el `codEstado` 3004 (`comprobante_duplicado`), 3005 (`conflicto_idempotencia`) o 3014 (`correo_no_disponible`). | Mira el `codEstado` en la tabla de códigos de abajo. | | `EcuafactRateLimitException` | `EcuafactApiException` | HTTP 429 con un `codEstado` distinto de 4004, normalmente 5005 (`limite_solicitudes`). | Espera `retryAfter` segundos y reintenta con la misma `idempotencyKey`. El SDK ya lo reintenta por defecto, así que la excepción llega cuando se agotan los intentos o si desactivaste `retryRateLimited`. | | `EcuafactQuotaException` | `EcuafactApiException` | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`): cupo agotado. | Amplía el cupo ([`GET /v1/consumo`](/v1/guias/consumo)). No reintentes. | | `EcuafactServerException` | `EcuafactApiException` | HTTP 5xx, con el `codEstado` 5001 (`error_interno`), 5002 (`servicio_no_disponible`), 5003 (`error_dependencia`) o 5004 (`tiempo_agotado`), tras agotar los intentos si el estado es reintentable. | Si `esReintentable` es `true`, reintenta más tarde con la misma `idempotencyKey`. | | `EcuafactApiException` | `EcuafactSdkException` | Cualquier otro estado de error de la API que no corresponda a las filas anteriores (por ejemplo, un 418). | Revisa `codEstado`, `msgError` y `errores`. | | `EcuafactInvalidResponseException` | `EcuafactSdkException` | La API respondió con un estado 2xx, pero el cuerpo está vacío o no es JSON válido. Trae `status`, `idempotencyKey` y `correlationId`. | No se reintenta. Si emitías, repite la emisión con la misma `idempotencyKey`, como se explica en [Idempotencia y reintentos](#idempotencia-y-reintentos), o consulta el resultado; no emitas de nuevo con otra clave. Si persiste, contacta a soporte con el `correlationId`. | | `EcuafactTipoComprobanteException` | `EcuafactSdkException` | El filtro `tipoDocumento` de `listarOperaciones` no es un tipo válido. | Usa el código (`01`, `03`, `04`, `05`, `06`, `07`) o su nombre. No llama a la API. | | `EcuafactResponseTooLargeException` | `EcuafactSdkException` | El cuerpo de la respuesta supera el tope `maxResponseBytes`. Trae `$limite` y `$bytesLeidos`. | Sube el tope o desactívalo si esperas archivos más grandes. No se reintenta. | | `EcuafactSdkException` | `\RuntimeException` | Otros errores locales: `Idempotency-Key` inválida, `idOperacion` que no es UUID, importe con formato inválido, falta el contribuyente por defecto, `identificacion` que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, `.` o `..`, argumento obligatorio vacío. | Corrige la llamada. | | Propiedad de `EcuafactApiException` | Tipo | Descripción | |---|---|---| | `codEstado` | `int` | Código numérico del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), por ejemplo 3002 o 3004. Úsalo para decidir, comparándolo con las constantes de `CodEstado`. Es 0 si la respuesta no trae cuerpo de error. | | `estado` | `?string` | `estado` de la respuesta de error, como `rechazado`, `rechazo_configuracion` o `error`. | | `msgError` | `?string` | Descripción general y fija del código. Muéstrala o regístrala, pero no la uses para decidir. | | `estadoHttp` | `int` | Estado HTTP. | | `errores` | `string[]` | Detalle específico del error, como la ruta del campo que falla en un 3002. Vacío cuando no hay detalle. | | `correlationId` | `?string` | Cabecera `X-Correlation-Id` (la de la API o la que enviaste en `RequestOptions`). Inclúyelo al pedir soporte. | | `idempotencyKey` | `?string` | Clave usada en la emisión; reutilízala al reintentar. `null` en llamadas sin idempotencia. | | `retryAfter` | `?int` | Segundos indicados por la cabecera `Retry-After`; `null` si no llegó. | | `esReintentable` | `bool` | `true` si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el `codEstado` 5005. El 429 con 4004 (cupo agotado) no es reintentable. | ```php emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001'); echo $r->admission->estado . ' ' . $r->admission->idOperacion . PHP_EOL; } catch (EcuafactValidationException $error) { // Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual. foreach ($error->errores as $detalle) { echo $detalle . PHP_EOL; } } catch (EcuafactQuotaException $error) { echo 'Cupo agotado: compra un paquete. No reintentes.' . PHP_EOL; } catch (EcuafactRateLimitException $error) { echo 'Limite de solicitudes: espera ' . ($error->retryAfter ?? 1) . " s y reintenta con {$error->idempotencyKey}" . PHP_EOL; } catch (EcuafactApiException $error) { echo "{$error->estadoHttp} codEstado {$error->codEstado} {$error->msgError} reintentable=" . var_export($error->esReintentable, true) . " correlation={$error->correlationId}" . PHP_EOL; } catch (EcuafactConnectionException | EcuafactTimeoutException $error) { // Sin conexion o sin respuesta: reintenta mas tarde con la MISMA Idempotency-Key. echo $error->getMessage() . " clave={$error->idempotencyKey}" . PHP_EOL; } ``` Estos son los códigos que verás con más frecuencia. El catálogo completo, con el nombre de cada código, está en [Errores](/v1/guias/errores#catalogo-de-codestado), y las constantes de `CodEstado` llevan ese mismo nombre, escrito con la convención del lenguaje. | `codEstado` | Nombre | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---|---| | 3009 | `credenciales_invalidas` | 401 | API Key ausente o inválida. | Corrige la API Key. No reintentes sin cambiar nada. | | 3010 | `ip_no_autorizada` | 403 | La IP no está permitida o no se pudo identificar. | Registra tu IP en **Cuenta > IP permitidas** o llama directo a la URL de la API, sin proxies intermedios; si persiste, contacta a soporte con el `correlationId`. | | 3011 | `acceso_denegado` | 403 | Contribuyente, tipo de comprobante no habilitado, o `ruc` distinto del contribuyente de la ruta. | Revisa `getContexto()` (`puedeEmitir`, `tiposComprobante`). | | 5005 | `limite_solicitudes` | 429 | Superaste el límite de solicitudes por minuto. | Espera `retryAfter` y reintenta con la misma `Idempotency-Key`, aunque el SDK ya lo hace por defecto; reduce el ritmo. | | 3003 | `solicitud_invalida` | 400 | JSON mal formado, cabecera inválida o parámetro de ruta con tipo inválido. | Corrige según `errores`. | | 3002 | `comprobante_invalido` | 422 | Campos del comprobante faltantes o mal formados, campos desconocidos o de otro tipo, o una regla fiscal incumplida (totales, impuestos). | Corrige según `errores`; consume 1 documento como intento. | | 3012 | `filtros_invalidos` | 400 | Un filtro de una consulta está fuera de rango. | Ajusta los filtros a los [límites](/v1/guias/limites). | | 3006 | `cuerpo_excedido` | 413 | Cuerpo mayor a 2 MiB en la emisión o 1 MiB en otros `POST`/`PUT`. | Reduce el cuerpo. | | 3004 | `comprobante_duplicado` | 409 | Ya existe un comprobante con ese número recibido, autorizado o rechazado por el SRI. | No reenvíes; si querías otro comprobante, omite `secuencial` para que se asigne el siguiente. | | 3005 | `conflicto_idempotencia` | 409 | Misma `Idempotency-Key` o `referenciaExterna` con otro contenido. | Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. | | 4004 | `cupo_agotado` | 429 | Se agotó el cupo de documentos. El SDK no lo reintenta. | Revisa `getConsumo()`; compra un paquete. | | 3013 | `no_encontrado` | 404 | Operación, comprobante o RIDE no encontrado. | Verifica el id, la clave y el ambiente; el RIDE existe solo si está autorizado. | | 5001, 5002, 5003, 5004 | `error_interno`, `servicio_no_disponible`, `error_dependencia`, `tiempo_agotado` | 500, 503, 502, 504 | Error interno, servicio no disponible, o el servicio de validación fiscal falló o no respondió. | El SDK ya reintentó; vuelve a intentar más tarde con la misma `Idempotency-Key`. | ## Idempotencia y reintentos La `Idempotency-Key` evita emitir dos veces el mismo comprobante si una llamada se repite, por ejemplo después de un timeout o de una caída de la red. - Si no la pasas, o pasas `''`, el SDK genera una de 32 caracteres hexadecimales, la usa en todos sus reintentos y te la devuelve en `$resultado->idempotencyKey` o, si falla, en `$error->idempotencyKey`. - Te recomendamos pasar un valor estable por intención, como tu número interno de factura, o un UUID v4 que guardes junto al documento. - El SDK valida la clave antes de enviarla con la misma regla de la API: de 1 a 128 caracteres, solo letras, dígitos y `-` `_` `.` `:` `/`. Si no cumple, lanza `EcuafactSdkException` sin llamar a la API. > [!WARNING] > Si reintentas una emisión desde tu aplicación, reutiliza la misma > `Idempotency-Key`. Una clave nueva para el mismo comprobante puede duplicar la > emisión. Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción (`EcuafactInvalidResponseException`) conserva la `Idempotency-Key` en `idempotencyKey` y el `X-Correlation-Id` en `correlationId`; repite la emisión con esa misma clave y no se duplica el comprobante. | Situación | Se reintenta | Detalle | |---|---|---| | HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con `retryableStatusCodes`. Solo en `GET` y en `POST`/`PUT` con `Idempotency-Key` (la emisión siempre la lleva). | | HTTP 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí, salvo con `retryRateLimited: false` | Espera lo que indica `Retry-After` y reintenta. Con `retryRateLimited: false` lanza `EcuafactRateLimitException` con `retryAfter`, y decides tú cuándo reintentar. | | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`) | Nunca | Esperar no repone el cupo. Lanza `EcuafactQuotaException`. | | Error de red o timeout de un intento | Sí | Se reintenta en las mismas condiciones; al agotar los intentos lanza `EcuafactConnectionException` o `EcuafactTimeoutException`. | | Descarga de RIDE/XML | Sí | Se reintenta ante un estado HTTP transitorio o un error de red. | | Validación sin emitir (`validar`, `validarEn`) | Sí | Se reintenta como una consulta ante un estado HTTP transitorio o un error de red. No lleva `Idempotency-Key` porque no emite nada. | | `actualizarPerfil`, `actualizarLogo` | No | No llevan `Idempotency-Key`, así que un reintento automático podría repetir el efecto. | | Cualquier otro 4xx | No | Se lanza la excepción de inmediato. | Entre intentos, el SDK espera según estas reglas, donde `n` es el número del intento que falló: - `Linear`: `retryBaseDelaySeconds` x `n`, más un margen aleatorio de hasta `retryJitterSeconds` x `n`. Con los valores por defecto, espera 0.2 s y 0.4 s, más hasta 0.05 s y 0.1 s. - `Exponential`: `retryBaseDelaySeconds` x 2^(`n`-1), más un margen aleatorio de hasta `retryJitterSeconds`. Si la respuesta trae un `Retry-After` mayor y `respectRetryAfter` es `true`, espera ese tiempo. Si `maxRetryDelaySeconds` es mayor que 0, la espera nunca lo supera. Si la siguiente espera no cabe en el tope total de la llamada, el SDK no reintenta y lanza el último error. ## Opciones por llamada Puedes cambiar el tiempo máximo, el tope total, la correlación, la cabecera `X-Additional-Info` o los reintentos de una sola llamada sin tocar la configuración del cliente. Todos los métodos del cliente y de la vista `EcuafactContribuyente` que llaman a la API aceptan como último argumento `?RequestOptions $opciones`, incluido `esperarResultado`. Lo que no indiques usa la configuración del cliente. | Argumento de `RequestOptions` | Valor por defecto | Qué hace | |---|---|---| | `timeout` | `null` (usa el del cliente) | Tiempo máximo de cada intento, en segundos. Mayor que 0. Se aplica con el transporte cURL o con uno que implemente `TimeoutOverrideTransportInterface`; con un transporte PSR-18 se ignora y lo controla tu cliente HTTP. | | `totalTimeout` | `null` (usa `totalTimeoutSeconds`) | Tope de la llamada, incluidos reintentos y esperas, en segundos. Al superarlo lanza `EcuafactTimeoutException`. Mayor que 0. | | `correlationId` | `null` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres `A-Z a-z 0-9 . _ -`. | | `reintentos` | `true` | `false` desactiva los reintentos solo en esta llamada. | | `validarAntes` | `null` (usa el del cliente) | Solo en `emitir` y `emitirEn`: `true` llama a `/validar` antes de emitir y `false` no lo llama, sea cual sea `validarAntesDeEmitir`. | | `additionalInfo` | `null` (usa el del cliente) | Valor de la cabecera `X-Additional-Info` en esta llamada; reemplaza al `additionalInfo` del cliente. Sigue la misma validación que en el cliente, descrita en [Información adicional](#informacion-adicional). Con `null` usa el del cliente, y con `''` no envía la cabecera en esta llamada. | PHP no tiene cancelación cooperativa, así que acota la llamada con `timeout` o `totalTimeout`. La API devuelve la correlación que enviaste. La encuentras en `EmisionResultado::$correlationId`, en `EcuafactApiException::$correlationId` y en `$correlationId` de `EcuafactConnectionException` y `EcuafactTimeoutException`. ```php getContexto(new RequestOptions( reintentos: false, correlationId: 'pedido-2026-0457', additionalInfo: 'erp=MiERP/4.2; sucursal=quito; caja=3', )); echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL; // Mas tiempo para una descarga grande, con tope total de 2 minutos. $ride = $client->descargarRide( '0123456789001', '0710202601012345678900110010010000001231234567811', new RequestOptions(timeout: 60.0, totalTimeout: 120.0), ); file_put_contents('ride.pdf', $ride->contenido); ``` Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu emisor. Un `correlationId` con espacios o de más de 64 caracteres, un `additionalInfo` inválido o un tiempo menor o igual a 0 lanzan `EcuafactConfigurationException` al crear `RequestOptions`, sin llamar a la API. ## Información adicional Puedes enviar un dato tuyo en cada solicitud, por ejemplo la versión de tu ERP o la sucursal que emite, para que ubiquemos tus llamadas cuando nos pidas soporte. Viaja en la cabecera `X-Additional-Info`; la API la asocia a tu solicitud y no cambia su respuesta. Es la única cabecera personalizada que admite el SDK. Las reglas de la API están en [Límites](/v1/guias/limites#cabeceras). | Dónde | Qué hace | |---|---| | `EcuafactClientOptions` argumento `additionalInfo` | Se envía en todas las solicitudes del cliente, incluidas las de `esperarResultado` y la vista `EcuafactContribuyente` (`$client->para(...)`). Con `null` o `''` no se envía. | | `RequestOptions` argumento `additionalInfo` | Reemplaza el valor del cliente solo en esa llamada. Con `null` usa el del cliente, y con `''` no envía la cabecera en esa llamada. | El SDK valida el valor en tu proceso, antes de llamar a la API, con estas reglas: - Solo caracteres ASCII imprimibles (0x20 a 0x7E): sin tildes, `ñ` ni saltos de línea. - Sin espacios al inicio ni al final. - Máximo 256 caracteres (`EcuafactClientOptions::ADDITIONAL_INFO_MAX`). Si no cumple, el constructor lanza `EcuafactConfigurationException` sin llamar a la API. El valor aparece como `***` en `var_dump` y no se incluye en las excepciones. No pongas en él la API Key ni datos personales. ```php getContexto(); // Solo esta llamada lleva otro valor. $consumo = $client->getConsumo(new RequestOptions( additionalInfo: 'erp=MiERP/4.2; sucursal=002; lote=2026-10-08', )); echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL; ``` | Error | Por qué pasa | Qué hacer | |---|---|---| | `EcuafactConfigurationException` al crear `EcuafactClientOptions` | `additionalInfo` tiene tildes, `ñ`, saltos de línea u otro carácter fuera de 0x20 a 0x7E, espacios al inicio o al final, o más de 256 caracteres. | Corrige el valor: quita tildes y espacios de los extremos y acórtalo. | | `EcuafactConfigurationException` al crear `RequestOptions` | El mismo problema en `additionalInfo` de la llamada. No se llamó a la API. | Corrige el valor de esa llamada. | ## Conexión: proxy, TLS y PSR-18 Si necesitas salir por un proxy, confiar en una CA propia o ajustar el tiempo de conexión, puedes configurarlo con las opciones del cliente. Por defecto el SDK usa cURL. ```php getContexto()->contribuyentes ?? []) . PHP_EOL; ``` Si tu aplicación ya usa un cliente PSR-18, como Guzzle o Symfony HttpClient, pásalo con `Transport\Psr18Transport`, que necesita el cliente y las fábricas PSR-17 de peticiones y de flujos. Con este transporte no se aplican `timeout`, `connectTimeout`, `proxy`, `caInfo`, `verifyPeer` ni `curlOptions`, así que configúralos en tu cliente. Los reintentos, `totalTimeoutSeconds` (que se comprueba antes de cada intento), la idempotencia, `additionalInfo` y las excepciones funcionan igual. Cuando tu cliente PSR-18 falla, el SDK decide entre `EcuafactTimeoutException` y `EcuafactConnectionException` por el tipo de la excepción. Con Guzzle mira el `errno` de cURL que trae `getHandlerContext()`, donde 28 es un timeout y cualquier otro valor es un error de conexión; con Symfony HttpClient busca una `TimeoutExceptionInterface` en la cadena de excepciones. Solo si la excepción no trae esa información, el SDK revisa si el mensaje dice `timeout` o `timed out`. Una `RequestExceptionInterface`, que indica que la petición no se pudo armar, sin esa información es siempre `EcuafactConnectionException`. La excepción original queda en `getPrevious()`. El ejemplo siguiente usa Guzzle, que instalas con `composer require guzzlehttp/guzzle`. ```php 30, 'connect_timeout' => 5, 'proxy' => 'http://proxy.miempresa.local:8080', ]); $fabrica = new HttpFactory(); // Fabrica PSR-17 de peticiones y de flujos. $client = new EcuafactClient(new EcuafactClientOptions( baseAddress: 'https://api-sandbox.mynexusapi.com/', apiKey: getenv('ECUAFACT_API_KEY'), transport: new Psr18Transport($guzzle, $fabrica, $fabrica), )); echo count($client->getContexto()->contribuyentes ?? []) . PHP_EOL; ``` ## Constructores de comprobantes Puedes armar la [Estructura del comprobante](/v1/guias/emision) con métodos en lugar de escribir el JSON. Los constructores son opcionales y están en `Ecuafact\Sdk\Builders`. Solo ensamblan la solicitud de su tipo (`FacturaRequest`, `NotaCreditoRequest`...) con los valores que les das: no calculan totales, impuestos ni redondeos, y no completan valores por defecto. Tú calculas los importes y la API los calcula y valida igual que si armaras el JSON a mano. ```php referencias('MiERP', 'FACTURA-2026-0002') ->fechaEmision(new DateTimeImmutable('now', new DateTimeZone('America/Guayaquil'))) ->comprador('07', '9999999999999', 'CONSUMIDOR FINAL') ->moneda('DOLAR') ->linea('SERV-001', 'Servicio de prueba', 1, '10.00', 0, Tarifa::iva('4', 15)) ->totalSinImpuestos('10.00') ->totalDescuento('0.00') ->propina('0.00') ->importeTotal('11.50') ->pago('01', '11.50') // Los importes de la linea y de totalConImpuestos los das tu: el SDK no los calcula. ->configurar(function (FacturaRequest $c): void { $c->detalles[0]->precioTotalSinImpuesto = '10.00'; $c->detalles[0]->impuestos[0]->baseImponible = '10.00'; $c->detalles[0]->impuestos[0]->valor = '1.50'; $fila = new Impuesto(); $fila->codigo = '2'; $fila->codigoPorcentaje = '4'; $fila->tarifa = '15'; $fila->baseImponible = '10.00'; $fila->valor = '1.50'; $c->info->totalConImpuestos = [$fila]; }); $comprobante = $factura->construir(); echo 'importeTotal ' . $comprobante->info->importeTotal . PHP_EOL; // 11.50 $r = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0002', new RequestOptions(correlationId: 'pedido-2026-0458')); echo $r->admission->estado . ' ' . $r->admission->idOperacion . ' ' . $r->correlationId . PHP_EOL; ``` Deberías ver `importeTotal 11.50` y luego `recibido pedido-2026-0458`. Si ejecutas el script otro día con la misma `Idempotency-Key`, la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`); en ese caso usa una `Idempotency-Key` y una `referenciaExterna` nuevas. Las seis fábricas reciben `($ruc, $estab, $ptoEmi)`. | Tipo | Fábrica | Métodos propios | |---|---|---| | Factura (`01`) | `ComprobanteBuilder::factura(...)` | `fechaEmision`, `comprador`, `linea`, `detalle`, `totalSinImpuestos`, `totalDescuento`, `propina`, `moneda`, `pago`, `importeTotal`, `guiaRemision` | | Liquidación de compra (`03`) | `ComprobanteBuilder::liquidacionCompra(...)` | `fechaEmision`, `proveedor`, `linea`, `detalle`, `totalSinImpuestos`, `totalDescuento`, `moneda`, `pago`, `importeTotal` | | Nota de crédito (`04`) | `ComprobanteBuilder::notaCredito(...)` | `fechaEmision`, `comprador`, `documentoModificado`, `motivo`, `linea`, `detalle`, `totalSinImpuestos`, `moneda`, `totalDocumentoSustento`, `valorModificacion` | | Nota de débito (`05`) | `ComprobanteBuilder::notaDebito(...)` | `fechaEmision`, `comprador`, `documentoModificado`, `motivo($razon, $valor)`, `iva`, `totalSinImpuestos`, `moneda`, `pago`, `valorTotal` | | Guía de remisión (`06`) | `ComprobanteBuilder::guiaRemision(...)` | `transportista`, `traslado`, `destinatario`, `linea` | | Retención (`07`) | `ComprobanteBuilder::retencion(...)` | `fechaEmision`, `sujetoRetenido`, `periodo`, `docSustento`, `impuestoSustento`, `lineaRetencion`, `pago` | Estas son las firmas de los métodos más usados: | Método | Firma | |---|---| | `linea` (01, 03, 04) | `linea($codigo, $descripcion, $cantidad, $precioUnitario, $descuento, Tarifa $iva, ?Tarifa $ice = null, ?string $codigoAuxiliar = null, ?array $detallesAdicionales = null)`. `$descuento` es un importe en dólares, no un porcentaje, y `$detallesAdicionales` admite hasta 3 pares `nombre => valor`. | | `comprador` | `comprador($tipoIdentificacion, $identificacion, $razonSocial, ?string $direccion = null)`. `proveedor` (03) tiene la misma firma. | | `pago` | `pago($formaPago, $total = null, ?int $plazo = null, ?string $unidadTiempo = null)` | | `documentoModificado` (04, 05) | `documentoModificado($codDocModificado, $numDocModificado, $fechaEmisionDocSustento)`. El número tiene la forma `ddd-ddd-ddddddddd`. | | `linea` (06) | `linea($codigoInterno, $descripcion, $cantidad, ?string $codigoAdicional = null)`; agrega el producto al destinatario de la guía. | | `destinatario` (06) | `destinatario($identificacion, $razonSocial, $direccion, $motivoTraslado, ?string $codEstabDestino = null, ?string $ruta = null, ?string $docAduaneroUnico = null)`. El constructor arma un solo destinatario, así que llamarlo otra vez reemplaza sus datos y conserva las líneas. Para varios destinatarios, usa `configurar`. | | `docSustento` (07) | `docSustento($codSustento, $codDocSustento, $numDocSustento, $fechaEmisionDocSustento, $fechaRegistroContable, $totalSinImpuestos = null, $importeTotal = null, ?string $numAutDocSustento = null, ?string $pagoLocExt = null)`. `$pagoLocExt` no tiene valor por defecto: se envía solo si lo indicas. | | `impuestoSustento` (07) | `impuestoSustento($codImpuesto, $codigoPorcentaje, $baseImponible, $tarifa, $valorImpuesto = null)`; `$valorImpuesto` se envía solo si lo indicas. | | `lineaRetencion` (07) | `lineaRetencion($codigo, $codigoRetencion, $baseImponible, $porcentajeRetener, $valorRetenido = null)`; `$valorRetenido` se envía solo si lo indicas. | Todos los constructores tienen además `referencias($origen, $externa)`, `secuencial`, `dirEstablecimiento`, `correo`, `telefono`, `infoAdicional($nombre, $valor)`, `configurar(fn (FacturaRequest $c) => ...)` (con la clase de su tipo; asigna cualquier campo del contrato) y `construir()`. `fechaEmision` acepta un texto `dd/MM/yyyy` o un `DateTimeInterface`; la guía de remisión no lo tiene y usa `traslado($dirPartida, $fechaInicio, $fechaFin)`. El ICE de una línea va en el séptimo argumento: `linea(..., Tarifa::iva('4', 15), Tarifa::ice('3011', 10))`. Los importes aceptan `int`, `float` o texto decimal como `'10.00'`, que es la forma exacta. **Lo que asignas se envía tal cual.** Todo valor que asignes (subtotal de línea, impuestos, bases, totales, propina, moneda, pagos) se envía exactamente como lo diste, y lo que no asignes no se envía: el constructor no completa totales, impuestos, `propina`, `moneda`, `pagoLocExt` ni el `total` de un pago. Los importes que das como texto decimal (`'10.00'`) conservan su precisión sin pérdida. Como `construir()` devuelve una copia, puedes seguir usando el constructor. | Elemento | Detalle | |---|---| | Tarifa de una línea | `Tarifa::iva($codigoPorcentaje, $tarifa)` o `Tarifa::ice($codigoPorcentaje, $tarifa)` con el `codigoPorcentaje` del [catálogo](/v1/guias/catalogos) y la `tarifa` en porcentaje (`15`, no `0.15`). El SDK envía la pareja tal como la defines. | | Importes | `int`, `float` o texto decimal. Un texto como `'10,50'` lanza `EcuafactSdkException` porque no se puede enviar sin perder precisión. | | Validación | Los constructores no validan reglas de negocio ni calculan: solo ayudan a armar el cuerpo. Valida con `$client->validar()` o emite y lee el 422 de la API, que es la única que calcula y decide. | ## Métodos Esta es la referencia de todos los métodos del cliente. Todos son síncronos y aceptan como último argumento `?RequestOptions $opciones`, que se explica en [Opciones por llamada](#opciones-por-llamada). La identificación que reciben es siempre el valor `identificacion` del contexto, y las clases de datos están en `Ecuafact\Sdk\Contracts`. | Método | Endpoint | Devuelve | |---|---|---| | `getContexto()` | `GET /v1/contexto` | `Contexto` (ver [Contexto y consumo](#contexto-y-consumo)) | | `emitir($comprobante, $idempotencyKey = null)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}` | `EmisionResultado` | | `emitirEn($identificacion, $comprobante, $idempotencyKey = null)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` | | `validar($comprobante)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionResultado` (revisa `valido`) | | `validarEn($identificacion, $comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionResultado` (ver [Validar sin emitir](#validar-sin-emitir)) | | `getOperacion($idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation`. `$idOperacion` debe ser un UUID. | | `consultarOperacion($idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias) | | `esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída. Opcional; tiempos en segundos. | | `descargarRide($identificacion, $claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | `ArchivoComprobante` (PDF) | | `descargarXml($identificacion, $claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | `ArchivoComprobante` (XML del comprobante autorizado) | | `getConsumo()` | `GET /v1/consumo` | `QuotaBucket` (ver [Contexto y consumo](#contexto-y-consumo)) | | `listarOperaciones($identificacion, $desde, $hasta, $tipoDocumento, $buscar, $pagina, $tamanoPagina)` | `GET /v1/operaciones` | `PaginaComprobantes` (ver [Listado de operaciones](#listado-de-operaciones)) | | `obtenerSalud()` | `GET /salud` | `bool`: `true` si el servicio responde. No envía API Key. Ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos). | | `obtenerEstadoServicio()` | `GET /estado` | `EstadoServicio` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)). No envía API Key. | | `listarCatalogos()` | `GET /v1/catalogos` | `Catalogos` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)) | | `obtenerCatalogo($nombre)` | `GET /v1/catalogos/{nombre}` | `CatalogoDetalle` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)) | | `getPerfil($identificacion)` | `GET /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` | | `actualizarPerfil($identificacion, PerfilEmisorUpdate $cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` | | `actualizarLogo($identificacion, $contenido, $contentType, $nombreArchivo = 'logo')` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (ver [Logo del perfil](#logo-del-perfil)) | | `consultarContribuyente($identificacion, $fusionar = true, $fuente = null)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta` | | `buscarContribuyentes($apellidos, $nombres = null, $clase = null, $max = null)` | `GET /v1/consultas/contribuyentes` | `BusquedaContribuyente[]` | | `listarEstablecimientos($ruc, $filtro = null)` | `GET /v1/consultas/establecimientos/{ruc}` | `EstablecimientosContribuyente` | | `validarIdentificacion($numero)` | `GET /v1/consultas/identificacion/validar/{numero}` | `ValidacionIdentificacion` (revisa `valido`) | | `decodificarClaveAcceso($claveAcceso)` | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | `ClaveAccesoDecodificada` | | `para($identificacion)` | - (no llama a la API; no recibe `RequestOptions`) | `EcuafactContribuyente` | | `options()` | - (no llama a la API) | `EcuafactClientOptions` | En `emitir`, `emitirEn`, `validar` y `validarEn`, `{ruta del tipo}` es la ruta de la tabla de [Tipo de comprobante y ruta](#tipo-de-comprobante-y-ruta). El cuerpo de esas cuatro llamadas es el de la clase del comprobante, sin ningún campo de tipo. Ten en cuenta además estos detalles de los métodos y de sus tipos: - `EmisionResultado` trae `admission`, `idempotencyKey` y `correlationId` (cabecera `X-Correlation-Id`). `admission` tiene los mismos campos que `Operation`, que se describen en [Seguimiento del resultado](#seguimiento-del-resultado). En una emisión aceptada, `estado` es `recibido` y `codEstado` es 1001 o 1002: con 1001, `claveAcceso` todavía es `null`, y con 1002 ya trae la clave de acceso. Tu código debe aceptar los dos valores. `urlEstado` es la URL completa del seguimiento. - Si no configuras `identificacion` en las opciones, `emitir` y `validar` lanzan `EcuafactSdkException`. En ese caso usa los métodos `...En` o `para()`. - `ArchivoComprobante` tiene `contenido` (`string` binario) y `contentType`. Las descargas solo existen con el comprobante autorizado; ver [Descargar XML](/v1/guias/consulta-xml). - `PerfilEmisorUpdate` tiene `nombreComercial`, `direccionMatriz`, `correo`, `telefono`, `ciudad` y `provincia`, y las propiedades en `null` no se envían. El detalle está en [Perfil del emisor](/v1/guias/perfil-emisor). ## Importes exactos En PHP un `float` es binario, y por eso `0.1 + 0.2` da `0.30000000000000004`. Los campos de importe, cantidad, precio y tarifa de la solicitud son `float|string|null`, y cada tipo se envía de una forma distinta. - Un **texto** decimal con punto, como `'11.50'`, se envía como número JSON literal (`11.50`), sin pasar por `float`. Es la forma exacta. - Un **float** se envía con 15 dígitos significativos, así que `0.1 + 0.2` viaja como `0.3`. - Un texto con otro formato, como `'10,50'` o `'1e3'`, se rechaza con `EcuafactSdkException` antes de llamar a la API. - Las propiedades en `null` no se envían. `Pago::$plazo` también acepta `float|string`. Calcula con `bcmath`, si la tienes, o en centavos enteros, y asigna el resultado como texto. ```php info->totalSinImpuestos = number_format($baseCentavos / 100, 2, '.', ''); // '10.00' $comprobante->info->importeTotal = number_format(($baseCentavos + $ivaCentavos) / 100, 2, '.', ''); // '11.50' echo $comprobante->info->importeTotal . PHP_EOL; // 11.50 ``` Si tu código lee esas propiedades con un tipo `float` estricto, conviértelas con `(float)`. En las respuestas, `Comprobante::$total` se lee como `float`. Las reglas de cálculo de cada comprobante están en [Factura](/v1/guias/emision-01). ## Varios contribuyentes Si no configuras `identificacion` en las opciones, usa los métodos `...En` o una vista por contribuyente. La vista repite la identificación por ti en cada método. ```php para('0123456789001'); $perfil = $matriz->getPerfil(); echo "{$perfil->razonSocial} ({$perfil->identificacion})" . PHP_EOL; ``` La vista `EcuafactContribuyente` tiene estos métodos, y todos aceptan `RequestOptions` al final. Además, `identificacion()` devuelve la identificación fija de la vista. | Método | Equivale a | |---|---| | `emitir($comprobante, $idempotencyKey = null)` | `$client->emitirEn($identificacion, $comprobante, $idempotencyKey)` | | `validar($comprobante)` | `$client->validarEn($identificacion, $comprobante)` | | `descargarRide($claveAcceso)` | `$client->descargarRide($identificacion, $claveAcceso)` | | `descargarXml($claveAcceso)` | `$client->descargarXml($identificacion, $claveAcceso)` | | `getPerfil()` | `$client->getPerfil($identificacion)` | | `actualizarPerfil($cambios)` | `$client->actualizarPerfil($identificacion, $cambios)` | | `actualizarLogo($contenido, $contentType, $nombreArchivo = 'logo')` | `$client->actualizarLogo($identificacion, ...)` | | `esperarResultado($idOperacion, $intervalo = 5.0, $maximo = 120.0)` | `$client->esperarResultado(...)` | | `getConsumo()` | `$client->getConsumo()` (el cupo es de la API Key, no del contribuyente) | ## Logo del perfil Con `actualizarLogo` puedes subir el logo que aparece en el RIDE de tu contribuyente sin armar la petición `multipart/form-data`; recibes el `PerfilEmisor` actualizado. La API acepta PNG o JPEG de hasta 512 KB; `$contenido` son los bytes del archivo y `$contentType` es `image/png` o `image/jpeg`. Un contenido vacío o un `contentType` con caracteres inválidos lanza `EcuafactSdkException` sin llamar a la API. La subida no se reintenta automáticamente. ```php actualizarLogo('0123456789001', file_get_contents('logo.png'), 'image/png', 'logo.png'); echo "Logo actualizado para {$perfil->razonSocial}: {$perfil->logo}" . PHP_EOL; ``` Las reglas del archivo y los errores posibles están en [Perfil del emisor](/v1/guias/perfil-emisor). ## Contexto y consumo Antes de emitir puedes preguntar con qué contribuyentes puedes trabajar y cuántos documentos te quedan. `getContexto()` lee el [contexto](/v1/guias/consulta-contexto) de tu API Key y `getConsumo()` lee tu [cupo](/v1/guias/consumo). Ninguna de las dos consume cupo. ```php getContexto(); foreach ($contexto->contribuyentes ?? [] as $c) { echo $c->identificacion . ' ' . var_export($c->puedeEmitir, true) . ' ' . implode(',', $c->tiposComprobante ?? []) . PHP_EOL; } $cupo = $client->getConsumo(); echo "Disponibles {$cupo->disponibles} de {$cupo->limiteDocumentos}; vigente hasta {$cupo->vigenteHasta}" . PHP_EOL; ``` `getContexto()` devuelve un `Contexto`. La `identificacion` de cada contribuyente es la completa que devuelve el contexto, y es la que va en las rutas y en `infoTributaria.ruc`. Todas las propiedades pueden ser `null`. | Propiedad | Tipo | Descripción | |---|---|---| | `idCliente` | `?string` | Identificador de tu integración. | | `nombre` | `?string` | Nombre de tu integración. | | `contribuyentes` | `?Contribuyente[]` | Contribuyentes habilitados para tu API Key en el ambiente de la URL. | | `Contribuyente::$identificacion` | `?string` | Identificación completa del contribuyente; úsala en las rutas. | | `Contribuyente::$puedeEmitir` | `?bool` | `true` si tu API Key puede emitir para este contribuyente. | | `Contribuyente::$puedeRecibir` | `?bool` | `true` si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión. | | `Contribuyente::$tiposComprobante` | `?string[]` | Códigos de los tipos de comprobante habilitados (`01`, `03`, `04`, `05`, `06`, `07`). | | `Contribuyente::$marcaBlanca` | `?bool` | `true` si el contribuyente es un emisor de marca blanca: sus comprobantes no tienen RIDE, y el XML se descarga igual. | `getConsumo()` devuelve un `QuotaBucket`. Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo, y uno cancelado no lo consume. | Propiedad | Tipo | Descripción | |---|---|---| | `limiteDocumentos` | `?int` | Documentos contratados en total: la suma de tus paquetes vigentes. | | `reservados` | `?int` | Documentos de emisiones recibidas que aún no tienen resultado final. | | `consumidos` | `?int` | Documentos descontados por emisiones con resultado final. | | `disponibles` | `?int` | Documentos que aún puedes emitir con tus paquetes vigentes. | | `vigenteHasta` | `?string` | Fecha y hora (ISO 8601, UTC) en que vence el próximo paquete con saldo. | | `limiteExtra`, `reservadosExtra`, `consumidosExtra`, `disponiblesExtra` | `?int` | Se mantienen por compatibilidad y valen 0: todo el saldo está en las cuatro propiedades anteriores. | El significado de cada valor, con un ejemplo numérico, está en [Consumo y cuotas](/v1/guias/consumo#respuesta). ## Listado de operaciones `listarOperaciones` devuelve una página de los comprobantes de un contribuyente (`GET /v1/operaciones`) y no consume cupo. La `identificacion` es obligatoria; los demás filtros son opcionales: `desde` y `hasta` en formato `yyyy-MM-dd`, `tipoDocumento` (el código o el nombre del tipo), `buscar` (número, clave de acceso, contraparte o referencia), `pagina` desde 1 y `tamanoPagina` de 1 a 100. Si un filtro no tiene el formato esperado, el SDK lanza `EcuafactSdkException` sin llamar a la API. ```php $pagina = 1; do { $resultado = $client->listarOperaciones( identificacion: '0123456789001', desde: '2026-11-01', hasta: '2026-11-30', pagina: $pagina, tamanoPagina: 50, ); foreach ($resultado->comprobantes as $fila) { echo $fila->numeroDocumento . ' ' . $fila->estado . ' ' . $fila->codEstado . ' ' . $fila->total . PHP_EOL; } $pagina++; } while ($resultado->hayMas); ``` La respuesta es un `PaginaComprobantes` con `comprobantes`, `pagina`, `tamanoPagina` y `hayMas`; mientras `hayMas` sea `true`, pide la página siguiente. Cada fila es un `Comprobante` con `claveAcceso`, `numeroDocumento`, `tipoDocumento`, `fechaEmision`, `identificacionContraparte`, `razonSocialContraparte`, `total`, `estado`, `codEstado`, `msgError`, `errores` y `fhAutorizacion`; `estadoOperacion()` y `tipoComprobante()` devuelven los valores tipados. La vista `$client->para($identificacion)` ofrece el mismo método con la identificación fija. ## Consultas SRI Con estos métodos puedes consultar el catastro del SRI, y no consumen cupo. ```php validarIdentificacion('0123456789001'); $contribuyente = $client->consultarContribuyente('0123456789001'); $encontrados = $client->buscarContribuyentes('PEREZ LOPEZ', 'JUAN', 'PersonaNatural', 10); $establecimientos = $client->listarEstablecimientos('0123456789001', 'SoloActivos'); $clave = $client->decodificarClaveAcceso('0710202601012345678900110010010000001231234567811'); echo var_export($validacion->valido, true) . ' ' . count($encontrados) . ' ' . $clave->rucEmisor . PHP_EOL; ``` Si un argumento obligatorio, como la identificación, los apellidos, el RUC, el número o la clave de acceso, llega vacío, el SDK lanza `EcuafactSdkException` sin llamar a la API. Los parámetros y las respuestas de cada consulta están en [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). ## Estado del servicio y catálogos Puedes consultar el estado público del servicio y los catálogos del SRI sin armar ninguna petición. `obtenerEstadoServicio()` lee el [estado del servicio](/v1/guias/estado-del-servicio) y no envía API Key ni consume cupo, así que sirve para comprobar la disponibilidad antes de configurar una credencial o desde tus propias alertas. `listarCatalogos()` y `obtenerCatalogo($nombre)` leen los [catálogos del SRI](/v1/guias/catalogos) con la API Key del cliente. Los catálogos cambian pocas veces al año, así que puedes guardar sus respuestas en caché por una hora. ```php obtenerEstadoServicio(); echo $estado->estado . ' ' . ($estado->disponibilidad90Dias ?? 'sin datos') . PHP_EOL; foreach ($estado->componentes ?? [] as $componente) { echo $componente->nombre . ' ' . $componente->estado . PHP_EOL; } foreach ($estado->incidentes ?? [] as $incidente) { echo $incidente->inicio . ' ' . $incidente->impacto . ' ' . $incidente->titulo . ' ' . ($incidente->fin ?? 'abierto') . PHP_EOL; } foreach ($client->listarCatalogos()->catalogos ?? [] as $resumen) { echo $resumen->nombre . ': ' . $resumen->descripcion . PHP_EOL; } try { $tarifas = $client->obtenerCatalogo('tarifas-iva'); foreach ($tarifas->items ?? [] as $fila) { echo $fila->codigo . ' ' . $fila->descripcion . ' ' . ($fila->valor ?? '') . PHP_EOL; } } catch (EcuafactNotFoundException) { echo 'Ese catálogo no existe' . PHP_EOL; } ``` Si el catálogo `tarifas-iva` existe, el script imprime una línea por cada código de IVA con su tarifa. Con una clave que no está en el índice, la API responde 404 con el `codEstado` 3013 (`no_encontrado`) y el SDK lanza `EcuafactNotFoundException`. Los demás errores siguen la jerarquía de [Errores](#errores). Un `nombre` vacío lanza `EcuafactSdkException` sin llamar a la API. ### Estado del servicio `obtenerEstadoServicio()` devuelve un `EstadoServicio` con los mismos campos que la [respuesta de la consulta](/v1/guias/estado-del-servicio#respuesta). Todas las propiedades pueden ser `null`. | Propiedad | Tipo | Descripción | |---|---|---| | `estado` | `?string` | Estado general: `operativo`, `degradado`, `caido` o `sin_datos`. | | `medidoEn` | `?string` | Momento de la última medición (ISO 8601, UTC). `null` si todavía no hay mediciones. | | `componentes` | `?ComponenteEstado[]` | Componentes monitoreados. | | `disponibilidad90Dias` | `float\|string\|null` | Porcentaje de minutos sin caída en los últimos 90 días. `null` si aún no hay muestras. | | `incidentes` | `?IncidentePublico[]` | Incidentes de los últimos 90 días y los que siguen abiertos, del más reciente al más antiguo. | | Propiedad de `ComponenteEstado` | Tipo | Descripción | |---|---|---| | `nombre` | `?string` | Nombre del componente. | | `estado` | `?string` | `operativo`, `degradado`, `caido` o `sin_datos`. | | Propiedad de `IncidentePublico` | Tipo | Descripción | |---|---|---| | `inicio` | `?string` | Inicio del incidente (ISO 8601, UTC). | | `fin` | `?string` | Fin del incidente. `null` mientras sigue abierto. | | `impacto` | `?string` | `degradado` o `caido`. | | `titulo` | `?string` | Título breve. | | `detalle` | `?string` | Qué significó para tus integraciones. `null` si no hay detalle. | Qué hacer ante cada `estado` se explica en [Valores de estado](/v1/guias/estado-del-servicio#valores-de-estado). Para comprobar solo que el servicio responde, `obtenerSalud()` llama a `GET /salud`, que no requiere API Key, y devuelve `true`; si la respuesta no es 2xx, lanza la excepción correspondiente. ### Catálogos `listarCatalogos()` devuelve un `Catalogos` y `obtenerCatalogo($nombre)`, un `CatalogoDetalle`. El `nombre` es la clave que devuelve el índice, como `tarifas-iva`; las claves disponibles están en [Catálogos disponibles](/v1/guias/catalogos#catalogos-disponibles). | Propiedad de `Catalogos` | Tipo | Descripción | |---|---|---| | `catalogos` | `?CatalogoResumen[]` | Catálogos disponibles, en el orden de la ficha técnica del SRI. | | Propiedad de `CatalogoResumen` | Tipo | Descripción | |---|---|---| | `nombre` | `?string` | Clave del catálogo; es el valor que recibe `obtenerCatalogo`. | | `descripcion` | `?string` | Descripción breve de lo que contiene. | | Propiedad de `CatalogoDetalle` | Tipo | Descripción | |---|---|---| | `nombre` | `?string` | Clave del catálogo. | | `descripcion` | `?string` | Descripción breve del catálogo. | | `fuente` | `?string` | Tabla o anexo de la ficha técnica del SRI de donde proviene. | | `items` | `?CatalogoItem[]` | Filas del catálogo. | | Propiedad de `CatalogoItem` | Tipo | Descripción | |---|---|---| | `codigo` | `?string` | Código tal como va en el comprobante. Envíalo como texto, con sus ceros a la izquierda cuando los tenga. | | `descripcion` | `?string` | Descripción del código. | | `valor` | `float\|string\|null` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. `null` si el catálogo no lo tiene. | | `vigenteDesde` | `?string` | Primer día de vigencia (`yyyy-MM-dd`). `null` si la fila no está acotada por el inicio. | | `vigenteHasta` | `?string` | Último día de vigencia (`yyyy-MM-dd`). `null` si sigue vigente. | | `atributos` | `?array` | Atributos propios del catálogo. `null` si no hay. | ## Siguientes pasos - [Factura](/v1/guias/emision-01): revisa todos los campos y las reglas de cálculo para construir tus comprobantes. - [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta qué significa cada `estado` y cada `codEstado`. - [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI sin consultar en bucle. - [Visión general de los SDK](/v1/guias/sdk): compara los cinco SDK y decide entre SDK o HTTP directo. --- # CLI de Ecuafact Emite, sigue y descarga comprobantes electrónicos desde la terminal con el CLI `ecuafact`, sin escribir código. Si necesitas hacer revisiones rápidas o conectar nuestros servicios de facturación a un proceso automatizado, puedes usar nuestro CLI `ecuafact`. Con él creas un comprobante de ejemplo, lo validas, lo emites, esperas la respuesta del SRI y descargas el RIDE con un par de comandos, sin programar las llamadas HTTP. Te sirve tanto para probar la API por primera vez como para emitir desde los archivos que genera tu ERP. En esta página instalas el CLI, lo conectas con tu API Key de pruebas y emites tu primera factura. Al final encontrarás la lista de comandos, agrupados por tarea, con enlaces a las guías y a la referencia donde se explica cada uno. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos de esta página usan el > entorno `sandbox`. ## 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: ```text Instala el CLI de Ecuafact y emite una factura de prueba desde esta terminal. 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/cli.md antes de escribir código; no inventes campos. Si ecuafact ya está instalado, reutilízalo; si no, instálalo con npm install -g @ecuafact/cli (o con Scoop o Homebrew si prefiero ese gestor). Fija el entorno con ecuafact config poner entorno sandbox. No pidas ni leas mi API Key: pídeme que ejecute yo mismo ecuafact login en mi terminal (la guarda sin mostrarla) o que defina ECUAFACT_API_KEY en mi entorno; nunca la pases como argumento de un comando, nunca la pegues en el chat ni la imprimas. Ejecuta ecuafact doctor y corrige lo que indique (clave, IP permitida, cupo); crea el comprobante con ecuafact nuevo factura --archivo factura.json, completa el RUC del emisor y los datos con los datos de prueba de la guía, valídalo con ecuafact validar factura.json y emítelo con ecuafact emitir factura.json --esperar. 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 los comandos e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer. ``` ## Instalación Instala el CLI con el gestor de paquetes que ya uses. **npm** ```bash npm install -g @ecuafact/cli ``` **Windows (Scoop)** ```powershell scoop bucket add ecuafact https://github.com/Ecuanexus/ecuafact-scoop scoop install ecuafact/ecuafact ``` **macOS y Linux (Homebrew)** ```bash brew install ecuanexus/ecuafact/ecuafact ``` Para actualizar, repite la instalación con npm o ejecuta `scoop update ecuafact` o `brew upgrade ecuafact`, según el gestor. Para comprobar qué versión tienes, ejecuta `ecuafact --version`. Si no muestra la versión que acabas de instalar, tienes otra instalación antes en el `PATH`: desinstala la que no uses. Para desinstalar el CLI, quita primero los servicios de [vigilancia de carpetas](/v1/guias/cli-vigilar) que hayas instalado, con `ecuafact vigilar desinstalar --nombre `, y luego desinstálalo con el mismo gestor: `npm uninstall -g @ecuafact/cli`, `scoop uninstall ecuafact` o `brew uninstall ecuafact`. ## Inicio rápido Necesitas una [API Key](/v1/guias/glosario#api-key) de pruebas. Si todavía no tienes una, crea tu [sandbox](/v1/guias/sandbox) desde el Portal del Cliente. En sandbox no hay que registrar la IP de tu equipo; en producción debe estar registrada en el portal, en **Cuenta > IP permitidas**. ```bash ecuafact config poner entorno sandbox ecuafact login ecuafact doctor ecuafact nuevo factura --archivo factura.json ecuafact emitir factura.json --esperar --descargar ride ``` Estos comandos hacen lo siguiente, en orden: 1. `config poner entorno sandbox` deja fijo en tu perfil el entorno de pruebas. 2. `login` te pide la API Key sin mostrarla en pantalla y la guarda. 3. `doctor` revisa la conexión, la API Key, tu IP y tu [cupo](/v1/guias/glosario#cupo). Si algo falla, te dice qué hacer. 4. `nuevo factura` crea una factura de ejemplo. Abre el archivo, pon tu [RUC](/v1/guias/glosario#ruc) y revisa los datos con la guía de [Factura](/v1/guias/emision-01). 5. `emitir` envía la factura, espera la [autorización](/v1/guias/glosario#autorizacion) del SRI y descarga el [RIDE](/v1/guias/glosario#ride). Si todo funcionó, el último comando muestra el comprobante con el estado `autorizado`: ```text ORIGEN ESTADO CODESTADO IDOPERACION CLAVEACCESO MENSAJE factura.json autorizado 2001 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f 0710202601012345678900110010010000001231234567811 Autorizado por el SRI. ``` El CLI guarda el RIDE en la carpeta actual, con la clave de acceso como nombre de archivo (`.pdf`). ## Autenticación El CLI se autentica siempre con una API Key. `ecuafact login` la guarda para el perfil y el entorno que estás usando. Para ver cuál está activa, ejecuta `ecuafact sesion`; para borrarla, `ecuafact logout`. En un servidor o en un proceso de integración continua, define la API Key en la variable de entorno `ECUAFACT_API_KEY`. El CLI la usa en lugar de la guardada en `sandbox` y `produccion`: ```bash export ECUAFACT_API_KEY="..." ecuafact --entorno sandbox consumo ``` > [!WARNING] > No pases la API Key como argumento de un comando, porque queda guardada en el > historial de la terminal. ## En scripts y CI Puedes usar el CLI en un servidor, una tarea programada o un pipeline de integración continua, porque ahí no te pregunta nada. Escribe el resultado en JSON por la salida estándar, los mensajes y los errores por la salida de errores, y termina con un [código de salida](/v1/guias/cli-referencia#codigos-de-salida) que tu script puede comprobar para saber si todo salió bien. Entrega la API Key con la variable `ECUAFACT_API_KEY`, que es lo más simple en un pipeline. Si prefieres guardarla una vez en el equipo, pásala por la entrada estándar con `login --desde-stdin`, para que no quede en el historial ni en la lista de procesos: ```bash echo "$ECUAFACT_KEY_SANDBOX" | ecuafact login --desde-stdin --entorno sandbox ``` En `produccion`, los comandos que emiten o cambian datos se detienen si no agregas `--confirmar produccion`, porque en un script nadie puede responder la confirmación. Este es un paso de GitHub Actions que emite una carpeta en pruebas, espera el resultado y guarda un reporte: ```yaml - run: npm install -g @ecuafact/cli - run: ecuafact --entorno sandbox emitir ./salida -r --esperar --reporte resultado.json env: ECUAFACT_API_KEY: ${{ secrets.ECUAFACT_API_KEY_SANDBOX }} ``` Revisa el código de salida y, si es distinto de 0, el reporte: ahí está el estado de cada comprobante. ## Entornos Puedes trabajar con dos entornos, uno por cada ambiente de la API. | Entorno | Para qué | |---|---| | `sandbox` | Pruebas, sin validez fiscal. | | `produccion` | Comprobantes reales. Es el entorno por defecto. | Como un perfil nuevo trabaja en `produccion`, elige el entorno antes de empezar a probar. Puedes indicarlo en cada comando con `--entorno sandbox` o dejarlo fijo en tu perfil con `ecuafact config poner entorno sandbox`. Cada entorno usa su propia API Key, así que ejecuta `login` una vez en cada uno. También puedes elegirlo con la variable `ECUAFACT_ENTORNO`, agregar entornos propios con `ecuafact entorno agregar` o probar contra un servidor local con `ECUAFACT_API_URL`; todo eso se explica en [Cambiar de ambiente o de URL](/v1/guias/cli-referencia#cambiar-de-ambiente-o-de-url). En `produccion`, los comandos que emiten o cambian datos te piden confirmación antes de seguir. Si los ejecutas desde un script, donde nadie puede responder, agrega `--confirmar produccion`. ## Configuración Con `config` guardas valores por defecto para no repetirlos en cada comando, y con `perfil` separas la configuración y las API Keys de cada integración, por ejemplo si trabajas para varias empresas. ```bash ecuafact config poner ruc 0123456789001 ecuafact config ver ecuafact perfil usar empresa-b ``` Puedes guardar el entorno, el RUC, el establecimiento, el punto de emisión y el formato de salida, entre otros. Todas las claves están en la [referencia](/v1/guias/cli-referencia#configuracion). Si trabajas en un proyecto, puedes fijar su configuración en un archivo `ecuafact.json` dentro del repositorio, sin la API Key. Ese archivo tiene prioridad sobre tu perfil; el orden completo está en [Precedencia y ecuafact.json](/v1/guias/cli-referencia#precedencia-y-ecuafact.json). ## Comandos Los comandos se agrupan por tarea. Cada grupo enlaza a la guía que lo explica con ejemplos, y la [referencia](/v1/guias/cli-referencia) tiene todas sus opciones. | Comando | Para qué | |---|---| | `emitir`, `validar`, `nuevo` | Crear, validar y emitir comprobantes desde JSON, JSONL, XML del SRI, carpetas, CSV o Excel ([Emitir con el CLI](/v1/guias/cli-emision)). | | `estado`, `lote` | Seguir operaciones y reanudar lotes. | | `descargar` | Descargar el RIDE y el XML. | | `vigilar` | Emitir lo que tu ERP deja en una carpeta ([Vigilar una carpeta](/v1/guias/cli-vigilar)). | | `plantilla` | Mapear las columnas de un CSV o Excel ([Emitir desde CSV o Excel](/v1/guias/cli-csv-excel)). | | `cuenta`, `consumo`, `perfil-emisor` | Ver tu integración, tu cupo y los datos del emisor. | | `ruc`, `identificacion`, `clave`, `establecimientos` | Hacer consultas al SRI. | | `salud`, `estado-servicio`, `catalogos` | Comprobar que el servicio responde y consultar su estado público (sin API Key), y consultar los catálogos del SRI. | | `webhooks` | Probar tu endpoint de webhooks. | | `login`, `config`, `perfil`, `entorno`, `doctor` | Gestionar credenciales y configuración, y diagnosticar problemas. | | `api`, `schema` | Llamar a cualquier ruta del API y describir el CLI en JSON. | El tipo del comprobante (`01` a `07`) elige la ruta de emisión y no viaja en el cuerpo. Lo indicas con `--tipo`, o el CLI lo deduce de la forma del comprobante ([Emitir con el CLI](/v1/guias/cli-emision)). Si necesitas ayuda en la terminal, `ecuafact --help` muestra la ayuda de cada comando y `ecuafact ayuda` lista guías breves que funcionan sin conexión. ## Siguientes pasos - [Emitir con el CLI](/v1/guias/cli-emision): emite lotes y carpetas, sigue cada comprobante y descarga sus archivos. - [Emitir desde CSV o Excel](/v1/guias/cli-csv-excel): emite desde las filas de tu archivo sin escribir JSON. - [Referencia de comandos](/v1/guias/cli-referencia): consulta todas las opciones y los códigos de salida. --- # Emitir con el CLI Emite uno o muchos comprobantes desde archivos JSON con `ecuafact emitir` y sigue cada uno hasta que el SRI responde. Con `ecuafact emitir` puedes emitir un comprobante, un lote de comprobantes o una carpeta entera, y ver el resultado de cada uno. Cada archivo lleva la misma estructura de [comprobante](/v1/guias/glosario#comprobante-electronico) que recibe la API, que se explica en [Emisión de comprobantes](/v1/guias/emision), así que puedes reutilizar los JSON que ya genera tu sistema. En esta página verás cómo emitir y validar antes de enviar, qué significa cada estado que muestra el CLI, cómo reanudar un lote que se cortó y cómo consultar y descargar lo que ya emitiste. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan el entorno > `sandbox` configurado en tu perfil, como se explica en el > [inicio rápido del CLI](/v1/guias/cli#inicio-rapido). ## Emitir ```bash ecuafact emitir factura.json --entorno sandbox ecuafact emitir lote.json ventas.jsonl --entorno sandbox ecuafact emitir ./pendientes -r --entorno sandbox ecuafact emitir factura.json --entorno sandbox --esperar --descargar ride,xml mi-erp exportar | ecuafact emitir - --entorno sandbox ``` `emitir` acepta archivos `.json` con un comprobante o con un array de comprobantes, archivos `.jsonl`, archivos `.xml` con un comprobante del SRI, carpetas y la entrada estándar si escribes `-`. En un XML, el tipo sale del elemento raíz del comprobante. Si tus datos están en un CSV o un Excel, sigue la guía [Emitir desde CSV o Excel](/v1/guias/cli-csv-excel). El tipo de comprobante elige la ruta de emisión (`/facturas`, `/liquidaciones-compra`, `/notas-credito`, `/notas-debito`, `/guias-remision` o `/retenciones`) y no viaja en el cuerpo de la petición. El CLI lo toma de estas fuentes, en este orden: 1. La opción `--tipo`: `factura`, `liquidacion`, `nota-credito` (o `nc`), `nota-debito` (o `nd`), `guia`, `retencion`, o el código `01`, `03`, `04`, `05`, `06` o `07`. 2. La forma del comprobante, cuando solo puede ser un tipo: `motivos` es una nota de débito (`05`), `destinatarios` una guía de remisión (`06`), `docsSustento` una retención (`07`); con `detalles`, `codDocModificado` o `valorModificacion` indican una nota de crédito (`04`), `razonSocialProveedor` o `identificacionProveedor` una liquidación de compra (`03`), y un comprador con `pagos` e `importeTotal` una factura (`01`). Por eso los comprobantes de ejemplo de la documentación se validan y se emiten sin indicar nada más. Si el CLI no puede decidir el tipo, o `--tipo` contradice a la forma del comprobante, rechaza el comprobante antes de enviarlo (código de salida 2) y el mensaje te pide indicar `--tipo`. El cuerpo que se envía es exactamente el esquema de ese tipo: el contrato tiene un esquema por tipo de comprobante y ninguno incluye `infoTributaria.tipoDocumento`. Si tu archivo trae ese campo, el CLI avisa, lo quita antes de enviar y sigue adelante; quítalo de tus archivos. ```bash ecuafact emitir liquidacion.json --tipo liquidacion --entorno sandbox ``` Al reanudar un lote con `ecuafact lote reanudar` no necesitas indicar el tipo de nuevo. Cuando un archivo del lote no se puede leer o convertir (JSON mal formado, XML que no es un comprobante del SRI, fila de CSV que no cumple la plantilla) o no permite elegir la ruta (falta el RUC o el tipo), el CLI no envía ningún comprobante del lote. Corrige el archivo y vuelve a ejecutar el comando, o agrega `--continuar-con-errores` si prefieres enviar los demás. Las reglas del comprobante (campos requeridos, formatos, catálogos, topes y totales) las aplica solo la API: `emitir` envía el comprobante directo y, si no cumple, muestra el 422 con su `codEstado` 3002 y la lista de `errores`. Puedes reenviar el mismo comprobante sin duplicarlo mientras conserve su `origenReferencia` y su [referenciaExterna](/v1/guias/glosario#referencia-externa). Por eso, cuando quieras emitir un comprobante nuevo o una versión corregida de uno rechazado, dale otra `referenciaExterna`. Un XML con exactamente el mismo contenido tampoco se duplica. Antes de emitir puedes revisar el comprobante sin emitir nada. `validar` envía cada comprobante a la API, en la ruta de validación de su tipo, con todas las reglas de la emisión, como se explica en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir); si la API lo acepta, el estado es `valido`, y las advertencias que devuelve se muestran sin bloquear. Localmente solo se comprueba que el archivo se pueda leer o convertir y que el tipo permita elegir la ruta. `emitir --dry-run` hace la misma validación y muestra lo que enviaría. Ninguno de los dos emite ni consume cupo. ```bash ecuafact validar factura.json ecuafact emitir factura.json --entorno sandbox --dry-run ``` La validación previa a la emisión es opcional y está apagada por defecto, para que cada emisión haga una sola petición. Si quieres que `emitir` valide cada comprobante antes de enviarlo, agrega `--validar-antes` o guarda `validarAntes` en `true` en la [configuración](/v1/guias/cli-referencia#configuracion). Con ella, el comprobante que la API declara inválido queda en estado `invalido` y no se emite, las advertencias se muestran sin bloquear, y cada comprobante cuesta dos peticiones. ```bash ecuafact emitir factura.json --validar-antes --entorno sandbox ``` Todas las opciones de `emitir` están en la [referencia](/v1/guias/cli-referencia#ecuafact-emitir). ## Resultado de cada comprobante Al terminar, el CLI muestra una fila por comprobante con su estado. Esta tabla dice qué significa cada uno y qué hacer. | Estado | Qué hacer | |---|---| | `autorizado` | No hagas nada. En `produccion` tiene validez fiscal. | | `recibido` | La API lo aceptó y todavía no tiene resultado final. Usa `--esperar` o consulta con `ecuafact estado `, y no lo emitas con otra `referenciaExterna`, porque lo duplicarías. | | `rechazado` | No se autorizó por su contenido. Si `codEstado` es 3001 (`rechazo_sri`), lo rechazó el SRI: corrígelo según el mensaje y emítelo con una `referenciaExterna` nueva y un secuencial nuevo. Si es 3002 (`comprobante_invalido`), corrígelo y emítelo de nuevo con una `referenciaExterna` nueva; puedes conservar el número. | | `rechazo_configuracion` | No se emitió porque falta o está mal una configuración del emisor, como la firma electrónica, la suscripción o el cupo. Corrige lo que indica `codEstado`, de 4001 a 4004, y emítelo de nuevo con una `referenciaExterna` nueva. | | `error` | No se pudo emitir. Si `codEstado` es 5006 (`entrega_no_posible`), emítelo de nuevo con una `referenciaExterna` nueva; si es 5007 (`resultado_no_confirmado`) o 5001 (`error_interno`), no lo emitas de nuevo y escribe a soporte con el `idOperacion`. | | `simulado` | Con `emitir --dry-run`: la API validó el comprobante y no se emitió nada. | | `valido` | Con `validar`: la API validó el comprobante con las reglas de la emisión. Si trae `advertencias`, no impiden emitir. | | `invalido` | No se envió: el archivo no se pudo leer o convertir, no permite elegir la ruta, o la API lo declaró inválido en la validación (`validar` o `--validar-antes`). Corrígelo según el mensaje. Si el mensaje pide `--tipo`, indica el tipo de comprobante. | | `no_enviado` | No se envió porque otro comprobante del lote no se pudo leer o no pasó la validación. | | `pendiente` | No se confirmó el envío. Reanuda el lote. | | `cancelado` | La plataforma canceló el envío y no se emitió. Emítelo con una `referenciaExterna` nueva. | Cada comprobante autorizado o rechazado consume un documento de tu [cupo](/v1/guias/glosario#cupo), y uno cancelado lo libera. Revisa lo que te queda con `ecuafact consumo`. Cada `codEstado` y qué hacer ante él se explican en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion). Si necesitas conservar el resultado, agrega `--reporte resultado.csv` (o `.json`). El CLI guarda una fila por comprobante, con su `idOperacion` y su [clave de acceso](/v1/guias/glosario#clave-de-acceso). ## Lotes Cada ejecución de `emitir` queda registrada como un lote, así que si se corta a la mitad, por ejemplo porque se cayó la conexión, puedes reanudarlo en el mismo entorno en el que lo empezaste sin duplicar los comprobantes que ya se enviaron. ```bash ecuafact lote listar ecuafact lote estado 20261017-093012-0a66 ecuafact lote reanudar 20261017-093012-0a66 --esperar ``` ## Seguimiento Para saber en qué quedó una emisión, consulta su operación con `estado`. ```bash ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f ``` ## Descargar `descargar` baja el RIDE y el XML de los comprobantes autorizados. Indica una o más claves de acceso. ```bash ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo ride,xml --entorno sandbox ``` ## Errores frecuentes | Mensaje | Qué hacer | |---|---| | `Credenciales inválidas.` | Ejecuta `ecuafact doctor` y revisa la API Key del entorno y, en producción, que tu IP esté registrada. | | `Contribuyente, tipo o suscripción no habilitados.` | Usa uno de tus contribuyentes, que puedes ver con `ecuafact cuenta`, y revisa el entorno. | | `Cupo insuficiente: ...` | Revisa tu cupo con `ecuafact consumo`. | | `Operacion en PRODUCCION sin confirmar` | En un script, agrega `--confirmar produccion`. | | `El lote es del entorno '...'` | Reanuda el lote con el mismo `--entorno` con el que lo emitiste. | ## Siguientes pasos - [Emitir desde CSV o Excel](/v1/guias/cli-csv-excel): emite desde las filas de tu archivo sin escribir JSON. - [Vigilar una carpeta](/v1/guias/cli-vigilar): emite automáticamente los archivos que deja tu ERP. - [Referencia de comandos](/v1/guias/cli-referencia): consulta todas las opciones y los códigos de salida. --- # Emitir desde CSV o Excel Emite comprobantes desde las filas de un CSV o de un Excel (`.xlsx`) con una plantilla que indica de qué columna sale cada campo. Si tu sistema exporta las ventas a una hoja de cálculo, puedes emitirlas desde ahí sin convertirlas a JSON. Escribes una vez una plantilla de mapeo, un archivo JSON que dice de qué columna sale cada campo del comprobante, y el CLI arma los comprobantes a partir de las filas de tu archivo cada vez que emites. En esta página creas una plantilla de ejemplo, la pruebas sin enviar nada y emites desde un CSV. Después encontrarás cómo se escriben las expresiones, las rutas de los campos y las líneas del comprobante, y qué hacer ante los errores más comunes. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan el entorno > `sandbox`. ## Inicio rápido Estos tres comandos crean una plantilla de ejemplo, la prueban y emiten en el ambiente de pruebas: ```bash ecuafact plantilla nueva factura ecuafact plantilla probar ejemplo-factura.csv --plantilla mapeo-factura.json ecuafact --entorno sandbox emitir ejemplo-factura.csv --plantilla mapeo-factura.json --esperar --reporte resultado.csv ``` 1. `plantilla nueva factura` crea la plantilla `mapeo-factura.json` y un archivo `ejemplo-factura.csv` que la usa. Abre la plantilla, pon tu [RUC](/v1/guias/glosario#ruc) en `infoTributaria.ruc` y cambia los nombres de columna por los de tu archivo. 2. `plantilla probar` muestra el JSON de cada comprobante que saldría del archivo, sin enviarlo. Si la plantilla está bien, cada uno trae las columnas de tu archivo en el campo que corresponde. Para que la API revise las reglas, ejecuta `ecuafact validar` con el mismo archivo. 3. `emitir` envía los comprobantes y guarda el resultado de cada uno en `resultado.csv`. Si tienes una carpeta de archivos CSV o Excel, indica qué leer con `--patron`, por ejemplo `ecuafact emitir ./ventas --plantilla mapeo-factura.json --patron "*.csv" --entorno sandbox`. ## Plantilla La plantilla es un archivo JSON. Dentro de `documento`, cada clave es un campo del comprobante y cada valor dice de qué columna sale ese campo o qué valor fijo lleva. Este es un ejemplo para una factura: ```json { "version": 1, "agruparPor": "numero", "documento": { "origenReferencia": "mi-erp", "referenciaExterna": "FAC-{numero}", "infoTributaria.ruc": "0123456789001", "infoTributaria.estab": "{establecimiento:digitos3}", "info.fechaEmision": "{fecha:fecha}", "info.importeTotal": "{importe_total:numero}" }, "lineas": { "coleccion": "detalles", "campos": { "codigoPrincipal": "{codigo}", "cantidad": "{cantidad:numero}", "impuestos[0].codigo": "2" } } } ``` | Clave | Descripción | |---|---| | `agruparPor` | Columna que identifica al comprobante: las filas con el mismo valor forman uno. Sin `agruparPor`, cada fila es un comprobante. | | `separador` | Solo CSV: `","`, `";"` o `"tab"`. Por defecto se detecta. | | `hoja` | Solo Excel: nombre de la hoja. Por defecto, la primera. | | `documento` | Campos del comprobante. Se toman de la primera fila del grupo. | | `lineas` | Líneas del comprobante, una por fila del grupo. | El tipo del comprobante (`01` factura, `03` liquidación de compra, `04` nota de crédito, `05` nota de débito, `06` guía de remisión o `07` retención) elige la ruta de emisión y no viaja en el cuerpo de la petición. Puedes indicarlo con `--tipo` al emitir o validar, o dejar que el CLI lo deduzca de las colecciones y los campos del comprobante, como se explica en [Emitir con el CLI](/v1/guias/cli-emision). La plantilla no lleva `infoTributaria.tipoDocumento`, porque el contrato no incluye ese campo y la API rechaza un cuerpo que lo traiga. Los campos de cada tipo de comprobante están en [Emisión de comprobantes](/v1/guias/emision). El CLI no calcula los totales, así que tu archivo debe traerlos ya calculados. ## Expresiones El valor de cada campo es una expresión. Entre llaves va el nombre de la columna y, si hace falta, el tipo al que se convierte la celda. | Expresión | Resultado | Ejemplo | |---|---|---| | `"{columna}"` | Texto de la celda. | `Av. Principal` → `"Av. Principal"` | | `"{columna:numero}"` | Número. Acepta coma o punto decimal. | `1.234,56` → `1234.56` | | `"{columna:entero}"` | Número entero. | `3` → `3` | | `"{columna:fecha}"` | Fecha `dd/MM/yyyy`. Acepta `yyyy-MM-dd`, `dd/MM/yyyy` y fechas de Excel. | `2026-10-16` → `"16/10/2026"` | | `"{columna:digitos3}"` | Dígitos con ceros a la izquierda (`digitos1` a `digitos20`), para códigos como `estab` o `formaPago`. | `1` → `"001"` | | `"texto"`, `0`, `true` | Valor fijo. | `"DOLAR"` | | `"FAC-{numero}"` | Texto fijo con columnas. | `000123` → `"FAC-000123"` | Si la celda está vacía, el campo no se incluye en el comprobante. ## Rutas La clave de cada campo es su ruta dentro del JSON del comprobante. Los niveles se separan con un punto y los elementos de una lista se indican con su índice entre corchetes, empezando en cero. Por ejemplo, `info.pagos[0].formaPago` es la forma de pago del primer pago y `info.totalConImpuestos[1].valor` es el valor del segundo total de impuestos. ## Líneas El bloque `lineas` arma la lista de líneas del comprobante, con una línea por cada fila del grupo. | Clave | Descripción | |---|---| | `coleccion` | `detalles` (factura, liquidación de compra, nota de crédito), `motivos` (nota de débito), `destinatarios` (guía de remisión) o `docsSustento` (retención). | | `campos` | Campos de cada línea, con rutas relativas a la línea. | ## Errores frecuentes Cada error indica la fila del archivo donde está el problema. ### Columna inexistente El mensaje `Columnas de la plantilla que no estan en ventas.csv: ...` indica que la plantilla nombra una columna que no existe en el archivo. Corrige el nombre de la columna en la plantilla o en la primera fila del archivo. ### Valor no numérico El mensaje `La columna 'cantidad' debe ser numerica; tiene 'dos'.` indica que una celda que debía tener un número tiene texto. Corrige la celda. ### Fecha inválida El mensaje `La columna 'fecha' debe ser una fecha ...` indica que la celda no tiene un formato de fecha que el CLI reconozca. Escribe la fecha como `dd/MM/yyyy` o `yyyy-MM-dd`. ### Hoja inexistente El mensaje `No existe la hoja 'Ventas'. Hojas: Hoja1, Hoja2.` indica que la hoja de la clave `hoja` no está en el Excel; el mensaje lista las que sí existen. Corrige el nombre o quita la clave para que el CLI use la primera hoja. ## Siguientes pasos - [Emitir con el CLI](/v1/guias/cli-emision): entiende el estado de cada comprobante y reanuda lotes. - [Vigilar una carpeta](/v1/guias/cli-vigilar): emite automáticamente los archivos que deja tu ERP. --- # Vigilar una carpeta Emite automáticamente cada comprobante que tu ERP deja en una carpeta, con el comando `ecuafact vigilar` o como un servicio del equipo. Si tu ERP no puede llamar a una API pero sí guarda cada comprobante como un archivo en una carpeta, puedes integrarlo sin cambiar su código. Con `ecuafact vigilar`, nuestro CLI revisa esa carpeta cada pocos segundos, emite cada archivo nuevo y lo mueve a otra carpeta según el resultado. En esta página verás cómo vigilar una carpeta desde la terminal, cómo dejar la vigilancia instalada como servicio para que arranque sola con el equipo y qué hacer ante los errores más comunes. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos usan el entorno > `sandbox`. ## Vigilar ```bash ecuafact --entorno sandbox vigilar ./bandeja ``` Mientras el comando está en ejecución, cada archivo que aparece en `./bandeja` se emite y después se mueve a una de estas carpetas: | Carpeta | Cuándo | |---|---| | `procesados/` | Todos sus comprobantes se enviaron bien. | | `errores/` | Algún comprobante tiene errores. Junto al archivo queda `.error.json` con el detalle. | Si falla la conexión o se agota el cupo, el archivo se queda en la bandeja y el CLI lo vuelve a intentar más tarde, sin duplicar los comprobantes. El CLI deduce el tipo de cada archivo por la forma del comprobante (o por la raíz, si es un XML del SRI) y con eso elige la ruta de emisión; el cuerpo no lleva ningún campo de tipo. Si no puede decidir el tipo, mueve el archivo a `errores/`. Estas opciones cambian cómo se vigila la carpeta: | Opción | Descripción | |---|---| | `--plantilla ` | Lee también CSV y Excel con esa plantilla ([Emitir desde CSV o Excel](/v1/guias/cli-csv-excel)). | | `--patron ` | Archivos a leer, separados por `;`. Por defecto `*.json;*.jsonl;*.ndjson;*.xml`, y con `--plantilla` también `*.csv;*.xlsx`. | | `--validar-antes` | Valida cada comprobante en la API antes de emitirlo; el que no cumple va a `errores/` sin emitirse. | | `-w`, `--esperar` | Espera la autorización del SRI antes de mover el archivo; un rechazo lo manda a `errores/`. | | `--descargar ride` | Descarga el RIDE de cada autorizado (`xml` o `ride,xml` también). | | `-d`, `--destino ` | Carpeta de las descargas. | | `--intervalo ` | Cada cuánto revisa la carpeta. Por defecto `10`. | | `--permitir-carpeta-compartida` | Acepta que otros usuarios con permiso de escritura en esa carpeta puedan emitir con tu API Key. Sin esta opción, usa una carpeta cuyos permisos estén restringidos. | | `--una-vez` | Revisa la carpeta una vez y termina, para una tarea programada o `cron`. Termina con 0 si todos los archivos salieron bien, con 7 si alguno fue a `errores/` y con el código del fallo si ninguno salió bien, así que tu tarea programada puede avisarte ([códigos de salida](/v1/guias/cli-referencia#codigos-de-salida)). | ## Como servicio Si no quieres depender de una terminal abierta, puedes instalar la vigilancia como un servicio que arranca junto con el equipo. El servicio usa la API Key y el entorno de tu perfil. ```bash # Windows, en una terminal como administrador ecuafact --entorno sandbox vigilar instalar C:\ERP\salida --nombre erp --destino C:\ERP\rides # Linux (systemd) y macOS sudo ecuafact --entorno sandbox vigilar instalar /srv/erp/salida --nombre erp --destino /srv/erp/rides ``` Después, consulta el estado del servicio o desinstálalo con el nombre que le diste: ```bash ecuafact vigilar estado --nombre erp ecuafact vigilar desinstalar --nombre erp ``` Al instalar el servicio, escribe las carpetas con rutas absolutas. En Linux y macOS puedes agregar `--usuario` para instalar un servicio de tu usuario, sin `sudo`. Si actualizas el CLI o quieres cambiar la API Key o el entorno, desinstala el servicio y vuelve a instalarlo. > [!WARNING] > Todo archivo válido que llegue a la carpeta se emite. Limita quién puede > escribir en ella, porque cualquiera con acceso podría emitir comprobantes con > tu API Key. ## Errores frecuentes | Mensaje | Qué hacer | |---|---| | `Instalar un servicio del sistema requiere permisos de administrador.` | Abre una terminal como administrador o usa `sudo`. En Linux y macOS también puedes instalar el servicio con `--usuario`. | | `No hay API Key para el perfil ...` al instalar con `sudo` | Guarda la API Key también para el administrador con `sudo ecuafact --entorno sandbox login`. | | `La carpeta ... la puede escribir ...` o `La carpeta vigilada puede ser escrita por ...` | Restringe sus permisos; al instalar puedes usar `--restringir-carpeta`. Si autorizas a esos usuarios a emitir con tu API Key, usa `--permitir-carpeta-compartida`. | | `Este equipo no usa systemd ...` | Programa `vigilar --una-vez` en `cron`. | ## Siguientes pasos - [Emitir con el CLI](/v1/guias/cli-emision): entiende el estado de cada comprobante y reanuda lotes. - [Webhooks](/v1/guias/webhooks): recibe en tu sistema el resultado del SRI de cada comprobante. - [Referencia de comandos](/v1/guias/cli-referencia#ecuafact-vigilar): consulta todas las opciones de `vigilar`. --- # Referencia de comandos del CLI Consulta cada comando del CLI `ecuafact` con sus opciones, las variables de entorno que acepta y los códigos de salida para tus scripts. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos que emiten usan el > entorno `sandbox`. ## Opciones globales Valen en cualquier comando. | Opción | Descripción | |---|---| | `-e`, `--entorno ` | `sandbox`, `produccion` u otro que hayas agregado con `entorno agregar` ([Cambiar de ambiente o de URL](#cambiar-de-ambiente-o-de-url)). | | `-p`, `--perfil ` | Perfil de configuración. Por defecto, el activo. | | `-o`, `--salida ` | `tabla`, `json` o `csv`. Por defecto, tabla en la terminal y JSON si rediriges la salida. | | `--campos ` | Campos a mostrar, separados por coma. Admite rutas con punto (`estado,claveAcceso`). | | `-q`, `--silencioso` | Muestra solo el resultado y los errores. | | `--confirmar ` | Confirma sin preguntar una operación que escribe en producción. El valor es el nombre del entorno de producción: `produccion` o, en un entorno propio marcado con `--produccion`, su nombre. | | `--version` | Muestra la versión del CLI. | | `-h`, `--help` | Muestra la ayuda del comando. | ## Emisión ### ecuafact emitir Emite uno o varios comprobantes. Alias: `emit`. ```text ecuafact emitir [opciones] ``` El tipo (`01` factura, `03` liquidación de compra, `04` nota de crédito, `05` nota de débito, `06` guía de remisión o `07` retención) elige la ruta de emisión y no se envía en el cuerpo. Sale de `--tipo` o de la forma del comprobante (en un XML, de su raíz), como se explica en [Emitir con el CLI](/v1/guias/cli-emision). Si no se puede decidir o hay contradicción, el comprobante se rechaza antes de enviarlo con código de salida 2. | Opción | Descripción | |---|---| | `` | Archivos `.json` (objeto o array), `.jsonl`, `.xml` (XML del SRI), `.csv` o `.xlsx` (con `--plantilla`), carpetas, o `-` para la entrada estándar. | | `-w`, `--esperar` | Espera el resultado del SRI. Por defecto, el valor de la clave `esperar`. | | `--espera-maxima ` | Tiempo máximo de espera, de 5 a 3600. Por defecto, 180. | | `--descargar ` | Descarga `ride`, `xml` o `ride,xml` al autorizarse. Implica `--esperar`. | | `-d`, `--destino ` | Carpeta de las descargas. Por defecto, la clave `carpetaDescargas` (la carpeta actual). | | `--tipo ` | Tipo de los comprobantes: `factura`, `liquidacion`, `nota-credito` (`nc`), `nota-debito` (`nd`), `guia`, `retencion`, o `01`, `03`, `04`, `05`, `06`, `07`. Sin la opción se deduce de la forma del comprobante. Si el archivo trae `infoTributaria.tipoDocumento`, el CLI avisa y lo quita al enviar. | | `--plantilla ` | Plantilla para leer CSV o Excel ([Emitir desde CSV o Excel](/v1/guias/cli-csv-excel)). | | `--patron ` | En carpetas, archivos a leer separados por `;`. Por defecto, `*.json;*.jsonl;*.ndjson;*.xml`. Para leer CSV o Excel de una carpeta, agrega `*.csv` o `*.xlsx`. | | `-r`, `--recursivo` | En carpetas, incluye las subcarpetas. | | `--validar-antes` | Antes de emitir, valida cada comprobante en la API (una petición más por comprobante). El que no cumple queda `invalido` y no se emite; las advertencias no bloquean. Por defecto, la clave `validarAntes` (`false`): sin esta opción se emite directo y la API responde 422 con los errores. | | `--dry-run`, `--simular` | Valida cada comprobante en la API con las reglas de la emisión ([Validar sin emitir](/v1/guias/emision#validar-sin-emitir)) y muestra lo que enviaría, sin emitir nada. | | `--continuar-con-errores` | Envía los válidos aunque otros tengan errores. | | `--reporte ` | Guarda el resultado de cada comprobante en un `.csv` o `.json`. | | `--mover-procesados ` | Mueve ahí los archivos enviados bien. | | `--mover-errores ` | Mueve ahí los archivos con errores, junto a su `.error.json`. | | `--concurrencia ` | Envíos simultáneos, de 1 a 10. Por defecto, la clave `concurrencia` (3). | | `--sin-verificar-cupo` | No compara el lote con el cupo antes de enviar. | ```bash ecuafact emitir factura.json --esperar --descargar ride --entorno sandbox ecuafact emitir ./pendientes -r --reporte resultado.csv --entorno sandbox ``` ### ecuafact validar Valida comprobantes en la API sin emitirlos. Alias: `validate`. ```text ecuafact validar [--tipo ] [--plantilla ] [--patron ] [-r] ``` `--tipo` funciona igual que en `emitir`. `validar` siempre envía cada comprobante a la API, en la ruta de validación de su tipo, con todas las reglas de la emisión, como se explica en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). Un comprobante que la API acepta queda en estado `valido`, con sus `advertencias` si las trae; uno que no cumple queda `invalido` con los `errores` de la API. No emite ni consume cupo. Localmente solo se comprueba que el archivo se pueda leer o convertir y que el tipo permita elegir la ruta. ### ecuafact nuevo Crea un comprobante de ejemplo. Alias: `new`. ```text ecuafact nuevo [-f, --archivo ] [--sobrescribir] ``` `` acepta `factura`, `liquidacion`, `nota-credito` (o `nc`), `nota-debito` (o `nd`), `guia`, `retencion` o el código, de `01` a `07`. ### ecuafact lote Consulta y reanuda las emisiones anteriores. Alias: `batch`. | Comando | Descripción | |---|---| | `lote listar [--limite ]` | Lista los lotes, del más reciente al más antiguo. Por defecto, 20. Alias: `ls`. | | `lote estado ` | Muestra el estado de cada comprobante del lote. | | `lote reanudar [--esperar] [--espera-maxima ] [--descargar ] [-d ]` | Reenvía los pendientes sin duplicar. Se ejecuta en el entorno del lote; `--descargar` implica `--esperar`. Alias: `resume`. | | `lote borrar ` | Borra el registro del lote. No afecta a los comprobantes. | ### ecuafact vigilar Emite cada archivo que aparece en una carpeta. Alias: `watch`. Guía: [Vigilar una carpeta](/v1/guias/cli-vigilar). ```text ecuafact vigilar [opciones] ecuafact vigilar instalar --nombre [opciones] ecuafact vigilar estado --nombre [--lineas ] ecuafact vigilar desinstalar --nombre ``` | Opción | Descripción | |---|---| | `--plantilla`, `--patron` | Igual que en `emitir`. Con `--plantilla`, el patrón por defecto incluye también `*.csv` y `*.xlsx`. | | `--validar-antes` | Valida cada comprobante en la API antes de emitirlo; el que no cumple va a `errores/`. Por defecto, la clave `validarAntes` (`false`). | | `-w`, `--esperar` | Espera el resultado del SRI antes de mover el archivo. | | `--descargar `, `-d`, `--destino ` | Igual que en `emitir`; `--descargar` implica `--esperar`. | | `--intervalo ` | Cada cuánto revisa la carpeta, de 2 a 3600. Por defecto, 10. | | `--una-vez` | Revisa una vez y termina. El [código de salida](#codigos-de-salida) dice si algún archivo falló. | | `--nombre ` | Nombre del servicio (`instalar`, `estado`, `desinstalar`). | | `--usuario` | En Linux y macOS, usa un servicio de tu usuario, sin `sudo`. Va en `instalar`, `estado` y `desinstalar`. | | `--restringir-carpeta` | Al instalar, deja la carpeta solo para administradores y tu usuario. | | `--permitir-carpeta-compartida` | En primer plano o al instalar, acepta que otros usuarios con permiso de escritura en la carpeta puedan emitir con tu API Key. | | `--lineas ` | En `estado`, las últimas líneas del registro del servicio. Por defecto, 15. | Alias de los subcomandos: `install`, `status` y `uninstall`. ### ecuafact plantilla Plantillas para emitir desde CSV o Excel. Alias: `template`. | Comando | Descripción | |---|---| | `plantilla nueva factura [-d ] [--sobrescribir]` | Crea una plantilla y un CSV de ejemplo. Alias: `new`. | | `plantilla probar --plantilla [--limite ] [--tipo ]` | Muestra los comprobantes que saldrían del archivo, sin enviarlos. Por defecto, 3. | ## Consulta | Comando | Descripción | |---|---| | `estado ` | Muestra el seguimiento de una operación ([Seguimiento](/v1/guias/consulta-operacion)). Alias: `status`. | | `operaciones listar [opciones]` | Lista los comprobantes de un contribuyente y un período ([Listado](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente)). Alias: `ls`. | | `descargar [--tipo ride,xml] [-d ] [--sobrescribir]` | Descarga el RIDE y el XML de comprobantes autorizados, como `.pdf` y `.xml`. Por defecto, solo el RIDE. Alias: `download`. | | `cuenta` | Muestra tu integración y sus contribuyentes. Alias: `contexto`. | | `consumo` | Muestra tu cupo de documentos. Cada comprobante autorizado o rechazado consume un documento y uno cancelado lo libera. Alias: `cupo`. | | `perfil-emisor ver` | Muestra los datos del emisor que salen en el RIDE ([Perfil del emisor](/v1/guias/perfil-emisor)). | | `perfil-emisor editar [--nombre-comercial] [--direccion-matriz] [--correo] [--telefono] [--ciudad] [--provincia]` | Cambia solo los datos que indicas. | | `perfil-emisor logo ` | Cambia el logo del RIDE. Acepta PNG o JPEG de hasta 512 KB. | `--ruc ` elige el contribuyente en los comandos que lo admiten, como `perfil-emisor`; acepta la identificación completa que devuelve `GET /v1/contexto`, por ejemplo el RUC de 13 dígitos. Por defecto, usa el de tu perfil o el único habilitado. ```bash ecuafact perfil-emisor editar --correo facturacion@ejemplo.com --telefono 042345678 --entorno sandbox ecuafact descargar --tipo ride,xml -d ./octubre --entorno sandbox ``` ### ecuafact operaciones listar Lista los comprobantes de un contribuyente y un período, con paginación. Alias: `ls`. ```text ecuafact operaciones listar [--identificacion ] [--desde ] [--hasta ] [--tipo ] [--buscar ] [--pagina ] [--tamano ] [--json] [--csv] ``` | Opción | Descripción | |---|---| | `--identificacion ` | Identificación del contribuyente, la misma de `GET /v1/contexto`. Si la omites, el comando usa el único contribuyente habilitado; con varios, se detiene y te pide esta opción, sin elegir uno. | | `--desde `, `--hasta ` | Fechas del período. Sin ninguna de las dos, la API usa los últimos 30 días. El rango máximo es de 366 días. | | `--tipo ` | `01` factura, `03` liquidación de compra, `04` nota de crédito, `05` nota de débito, `06` guía de remisión o `07` retención. | | `--buscar ` | Texto libre de hasta 100 caracteres. | | `--pagina ` | Página desde 1. Por defecto, 1. | | `--tamano ` | Comprobantes por página, de 1 a 100. Por defecto, 20. | | `--json` | Equivale a `--salida json`; devuelve la página completa, con `comprobantes`, `pagina`, `tamanoPagina` y `hayMas`. | | `--csv` | Equivale a `--salida csv`; escribe una fila por comprobante. | La tabla muestra el número, el tipo, la fecha, el estado, el `codEstado`, el total, la identificación de la contraparte y la clave de acceso. Si la respuesta trae `hayMas` en `true`, repite el comando con `--pagina` una unidad mayor; el mensaje de resumen te indica cuál. `--json` y `--csv` no se pueden combinar en la misma llamada. ```bash ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --tipo 01 --entorno sandbox ecuafact operaciones listar --identificacion 0123456789001 --buscar FAC --pagina 2 --tamano 50 --json ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --csv > emitidos.csv ``` ## Consultas al SRI | Comando | Descripción | |---|---| | `ruc consultar [--fusionar ] [--fuente ]` | Muestra los datos de un contribuyente. `--fusionar` combina las fuentes (por defecto, `true`) y `--fuente` acepta `Todas` (por defecto) o `SriCatastro`. | | `ruc buscar --apellidos [--nombres ] [--clase ] [--max ]` | Busca contribuyentes por nombre. `--clase` acepta `PersonaNatural` (por defecto), `Sociedad` o `SociedadPublica`; `--max`, de 1 a 30 (por defecto, 10). | | `identificacion validar ` | Valida una cédula, un RUC o un pasaporte. Alias del grupo: `cedula`. | | `clave decodificar ` | Descompone una clave de acceso. | | `establecimientos [--filtro ]` | Lista los establecimientos de un RUC. `--filtro` acepta `Todos` (por defecto), `SoloActivos`, `SoloCerrados`, `SoloMatriz` o `SoloSucursales`. | ## Estado del servicio y catálogos `salud` y `estado-servicio` no requieren API Key ni sesión: consultan `GET /salud` y `GET /estado`. `catalogos` consulta `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}` con la API Key del perfil y el entorno actuales. | Comando | Descripción | |---|---| | `salud` | Comprueba que el servicio responde (`GET /salud`, sin API Key). | | `estado-servicio` | Muestra el estado público del servicio: el estado general, la disponibilidad de los últimos 90 días, el estado de cada componente y los incidentes. Alias: `servicio`. Con `--salida json` devuelve la respuesta completa. | | `catalogos [nombre]` | Sin nombre, lista los catálogos del SRI con su clave y descripción. Con el nombre de un catálogo (por ejemplo `tarifas-iva`), muestra sus filas: código, descripción, valor y vigencia. En JSON conserva también `fuente` y los `atributos` de cada fila. Alias: `catalogo`. | ```bash ecuafact estado-servicio ecuafact estado-servicio --salida json --campos estado,disponibilidad90Dias ecuafact catalogos ecuafact catalogos tarifas-iva ecuafact catalogos tarifas-iva --salida json --campos items ``` Si el nombre del catálogo no existe, el comando termina con el código de salida 8. Si `catalogos` se ejecuta sin API Key, termina con el código 3. ## Webhooks El grupo `webhooks destinos` administra los destinos por API con la API Key del perfil y el entorno actuales. `webhooks probar` y `webhooks verificar` trabajan con tu endpoint y no llaman a la API; los dos leen el secreto del destino de la variable `ECUAFACT_WEBHOOK_SECRET`, o de la entrada estándar con `--secreto-desde-stdin`. ### ecuafact webhooks destinos Administra los destinos de [webhooks](/v1/guias/webhooks#administrar-destinos-por-api). Las operaciones que escriben piden confirmación en producción, como el resto de comandos del CLI. | Comando | Descripción | |---|---| | `destinos listar` | Lista los destinos que puede ver la API Key (`GET /v1/webhooks/destinos`). Alias: `ls`. | | `destinos crear --url [--eventos ] [--ruc ] [--mostrar-secreto]` | Crea un destino (`POST /v1/webhooks/destinos`). `--url` exige HTTPS en el puerto 443, sin credenciales ni fragmento. `--eventos` acepta una lista separada por coma; por defecto, los cuatro eventos. `--ruc` limita el destino a ese contribuyente. | | `destinos ver ` | Muestra un destino (`GET /v1/webhooks/destinos/{id}`). Alias: `obtener`. | | `destinos eventos --eventos ` | Reemplaza los eventos suscritos del destino (`PUT .../eventos`). Alias: `actualizar`. | | `destinos probar-destino ` | Pide a la plataforma que envíe un evento de prueba firmado al destino registrado (`POST .../probar`). Para probar cualquier URL desde tu equipo usa `webhooks probar`. | | `destinos pausar ` | Pausa las entregas nuevas (`POST /v1/webhooks/destinos/{id}/pausar`). | | `destinos reanudar ` | Reactiva un destino pausado (`POST .../reanudar`). | | `destinos rotar [--mostrar-secreto]` | Genera un secreto nuevo y lo devuelve una vez (`POST .../rotar-secreto`). | | `destinos entregas ` | Lista las últimas 50 entregas (`GET .../entregas`). | | `destinos intentos ` | Lista los intentos de una entrega (`GET .../entregas/{entregaId}/intentos`). `entregaId` es el campo `publicId` de la entrega. | | `destinos reintentar ` | Reenvía un evento ahora (`POST .../entregas/{eventoId}/reintentar`). `eventoId` es el campo `eventId` de la entrega. | | `destinos deshabilitar ` | Da de baja el destino; no se puede reactivar (`POST .../deshabilitar`). | `` es el `publicId` del destino. `crear` y `rotar` devuelven el secreto una sola vez: en la salida de tabla se muestra, y con `--salida json` o `--salida csv` solo aparece si agregas `--mostrar-secreto`. El CLI no guarda el secreto en ningún archivo ni lo escribe en un mensaje, así que cópialo y guárdalo en tu servidor en ese momento. ```bash ecuafact webhooks destinos listar --entorno sandbox ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact --entorno sandbox ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact \ --eventos document.authorized,document.failed --ruc 0123456789001 --entorno sandbox ecuafact webhooks destinos pausar --entorno sandbox ecuafact webhooks destinos rotar --entorno sandbox ecuafact webhooks destinos entregas --entorno sandbox ecuafact webhooks destinos reintentar --entorno sandbox ecuafact webhooks destinos deshabilitar --entorno sandbox ``` ### ecuafact webhooks probar Envía a tu endpoint un evento de ejemplo firmado y muestra lo que respondió. Alias: `test`. El evento lleva las mismas cabeceras de firma que una entrega real, `Ecuafact-Signature` y las de Standard Webhooks, así que sirve para probar tu endpoint con cualquiera de los dos esquemas. | Opción | Descripción | |---|---| | `--a ` | URL de tu endpoint. Exige HTTPS, sin credenciales ni fragmento; HTTP solo se acepta en `localhost`. Si tu endpoint no responde con un código de éxito, el comando termina con el código de salida 1. | | `--evento ` | `document.authorized` (por defecto), `document.rejected`, `document.failed` u `operation.requires_attention`. | | `--cod-estado ` | `codEstado` del cuerpo, un número de 4 dígitos. Solo admite las combinaciones que puede traer un evento real, que se detallan después de esta tabla. El `estado`, el `msgError` y `errores` del cuerpo se ajustan al código. | | `--clave-acceso ` | Clave de acceso del cuerpo. Por defecto, una de ejemplo. | | `--id-operacion ` | `idOperacion` del cuerpo. Por defecto, uno nuevo en cada envío. | | `--firma-invalida` | Envía una firma incorrecta, para comprobar que tu endpoint la rechaza con un 401. | | `--secreto-desde-stdin` | Lee el secreto de la entrada estándar. | Cada evento admite solo los códigos con los que te llega en una entrega real. `document.authorized` lleva siempre 2001. Con `document.rejected` puedes usar 3001, el rechazo del SRI, que es el valor por defecto y llega con un mensaje del SRI de ejemplo en `errores`, o 4002, la firma electrónica no válida. Con `document.failed` puedes usar 3002, 4001, 4002, 4003, 4004, 5001, 5006, que es el valor por defecto, o 5007. Con `operation.requires_attention`, si no indicas `--cod-estado` recibes el evento de prueba del portal, con `probe` en `"true"`. Si indicas 1001, o 1002 para que traiga `claveAcceso`, recibes el aviso de que el comprobante sigue `recibido` sin un resultado confirmado, con el motivo en `errores`. No hay opción para 6001, porque un comprobante cancelado no genera evento. Si pides una combinación que no existe, el comando termina con el código de salida 2 y no envía nada. Qué significa cada código se explica en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion). ```bash ecuafact webhooks probar --a http://localhost:5000/webhooks ecuafact webhooks probar --a http://localhost:5000/webhooks --evento document.failed --cod-estado 4002 ecuafact webhooks probar --a http://localhost:5000/webhooks --evento operation.requires_attention --cod-estado 1001 ``` ### ecuafact webhooks verificar Comprueba la firma de un webhook que ya recibiste. Alias: `verify`. Verifica la cabecera `Ecuafact-Signature` con `--firma`, o las tres cabeceras de [Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks) con `--webhook-id`, `--webhook-timestamp` y `--webhook-signature` juntas; no se pueden combinar los dos esquemas en la misma llamada. El resultado indica en `esquema` cuál verificó. | Opción | Descripción | |---|---| | `--firma ` | Valor de la cabecera `Ecuafact-Signature` (`t=...,v1=...`). | | `--webhook-id ` | Valor de la cabecera `webhook-id`. | | `--webhook-timestamp ` | Valor de la cabecera `webhook-timestamp`. | | `--webhook-signature ` | Valor de la cabecera `webhook-signature` (`v1,...`). | | `--cuerpo <@archivo>` | Cuerpo crudo, desde un archivo o `-` para la entrada estándar. | | `--tolerancia ` | Diferencia admitida con la marca de tiempo. Por defecto, 300. | | `--ahora ` | Instante de comparación en segundos Unix, para revisar un evento antiguo. Por defecto, ahora. | | `--secreto-desde-stdin` | Lee el secreto de la entrada estándar. | ```bash ecuafact webhooks verificar --firma "t=1791385446,v1=a1ae..." --cuerpo @evento.json --ahora 1791385446 ecuafact webhooks verificar --webhook-id 9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b --webhook-timestamp 1791385446 --webhook-signature "v1,6Ygt..." --cuerpo @evento.json --ahora 1791385446 ``` El resultado trae `valida`, `esquema`, `motivo`, `detalle`, `marca` (la marca de tiempo de la firma) y `edadSegundos`. Si la firma es válida, `motivo` es `null` y el comando termina con 0. Si no lo es, termina con 4 y `motivo` te dice la causa, mientras `detalle` la explica: | `motivo` | Qué pasó | Qué hacer | |---|---|---| | `cabecera_invalida` | La cabecera no trae `t` y `v1`, o faltan `webhook-id` o `webhook-timestamp` válidos. | Copia las cabeceras completas de la entrega. | | `secreto_invalido` | El secreto no tiene el formato esperado para Standard Webhooks. | Copia el secreto completo desde el portal, con o sin el prefijo `whsec_`. | | `firma_no_coincide` | La firma no corresponde a ese secreto y ese cuerpo. | Revisa que uses el secreto del destino correcto y el cuerpo exactamente como llegó, sin reformatearlo ni cambiar los fines de línea. | | `fuera_de_tolerancia` | La firma es correcta, pero la marca de tiempo está fuera de la tolerancia. | Para revisar un evento antiguo, pasa `--ahora` con su marca de tiempo. | ## Configuración ### ecuafact login Guarda la API Key del perfil y el entorno actuales. Sin opciones, la pide sin mostrarla. ```text ecuafact login [--desde-stdin] [--sin-verificar] ``` | Opción | Descripción | |---|---| | `--desde-stdin` | Lee la API Key de la entrada estándar, para scripts. | | `--sin-verificar` | Guarda la API Key sin probarla contra la API. | ```bash ecuafact login --entorno sandbox echo "$ECUAFACT_KEY_SANDBOX" | ecuafact login --desde-stdin --entorno sandbox ``` ### Otros comandos de configuración | Comando | Descripción | |---|---| | `logout` | Borra la API Key guardada del perfil y el entorno. | | `sesion` | Muestra el perfil, el entorno, la URL de la API y de dónde sale la API Key, sin mostrarla. Termina con el código 3 si no hay API Key. Alias: `whoami`. | | `config ver` | Muestra la configuración efectiva, la URL de la API en uso y de dónde sale cada valor. | | `config obtener `, `poner `, `quitar ` | Lee, guarda o borra una clave del perfil. Alias: `get`, `set`, `unset`. | | `config claves` | Lista las claves, su variable de entorno y su valor por defecto. | | `config ruta` | Muestra dónde está el archivo de configuración de tu usuario. | | `perfil usar `, `listar`, `borrar ` | Activa (o crea), lista o borra perfiles. Alias de `listar`: `ls`. | | `entorno listar`, `agregar --api [--produccion]`, `quitar ` | Lista los entornos y cuál está en uso, y agrega o quita entornos propios. `--produccion` hace que el entorno pida confirmación al escribir, como `produccion`. Alias de `listar`: `ls`. | | `doctor [--sin-ip-publica]` | Revisa la versión, la configuración, el entorno (y de dónde sale), la conexión, el reloj, la API Key, la IP, el cupo y los contribuyentes. Termina con el código 1 si alguna revisión falla. Si la autenticación falla, consulta tu IP pública en `api.ipify.org`; `--sin-ip-publica` evita esa consulta. | ### Cambiar de ambiente o de URL Para elegir el ambiente, usa `--entorno sandbox` o `--entorno produccion` en un comando, define la variable `ECUAFACT_ENTORNO` o déjalo fijo en tu perfil con `ecuafact config poner entorno `. Si necesitas apuntar a otro servidor, agrega un entorno propio con `ecuafact entorno agregar --api `. La URL debe usar HTTPS, salvo `localhost`, y `sandbox` y `produccion` no se pueden redefinir. Con `--produccion`, el entorno propio pide confirmación al escribir y, en un script, se confirma con `--confirmar `. Cada entorno guarda su propia API Key: ejecuta `login` en cada uno, y el CLI solo envía la API Key guardada al entorno con el que la guardaste. Si cambias la URL de un entorno propio con `entorno agregar`, el CLI borra las API Key guardadas para ese entorno y debes ejecutar `login` de nuevo. Cuando prefieres no guardar la API Key, defínela en la variable `ECUAFACT_API_KEY`. Como la entregas tú de forma explícita, el CLI la usa con cualquier URL (`sandbox`, `produccion`, un entorno propio o una URL definida con `ECUAFACT_API_URL`) y tiene prioridad sobre la guardada. Por eso conviene definirla solo en el proceso que la necesita y comprobar a qué URL apunta con `ecuafact sesion`, que muestra el entorno, la URL y el prefijo de la clave. La variable `ECUAFACT_API_URL` reemplaza la URL del entorno actual y sirve para apuntar a otro servidor, por ejemplo uno local. El entorno conserva su nombre y su comportamiento, así que con `produccion` sigue pidiendo confirmación. Con `ECUAFACT_API_URL` el CLI no usa la API Key guardada, porque ya no apunta al entorno con el que la guardaste: si no defines `ECUAFACT_API_KEY`, el comando termina con el código de salida 3 y te indica que la definas. | Quieres usar | Qué API Key envía el CLI | |---|---| | `sandbox` o `produccion` | La de `ECUAFACT_API_KEY`; si no existe, la guardada con `login` en ese entorno. | | Un entorno propio (`entorno agregar`) | La de `ECUAFACT_API_KEY`; si no existe, la guardada con `login --entorno `. | | Cualquier entorno con `ECUAFACT_API_URL` | Solo la de `ECUAFACT_API_KEY`. | ```bash ecuafact entorno agregar pruebas --api https://api.ejemplo.com ecuafact entorno listar echo "$API_KEY" | ecuafact --entorno pruebas login --desde-stdin ecuafact --entorno pruebas consumo export ECUAFACT_API_URL=http://localhost:5000 export ECUAFACT_API_KEY="..." ecuafact --entorno sandbox consumo ``` ### Claves y variables de entorno | Clave | Variable de entorno | Descripción | |---|---|---| | `entorno` | `ECUAFACT_ENTORNO` | Entorno por defecto: `sandbox`, `produccion` o uno propio. Por defecto, `produccion`. | | `ruc` | `ECUAFACT_RUC` | Identificación completa del contribuyente por defecto, como la devuelve `GET /v1/contexto` (por ejemplo, el RUC de 13 dígitos). | | `establecimiento` | `ECUAFACT_ESTABLECIMIENTO` | Establecimiento por defecto. | | `puntoEmision` | `ECUAFACT_PUNTO_EMISION` | Punto de emisión por defecto. | | `salida` | `ECUAFACT_SALIDA` | Formato de salida: `auto` (por defecto: tabla en la terminal y JSON si rediriges), `tabla`, `json` o `csv`. | | `concurrencia` | `ECUAFACT_CONCURRENCIA` | Envíos simultáneos. Por defecto, 3. | | `carpetaDescargas` | `ECUAFACT_CARPETA_DESCARGAS` | Carpeta de las descargas. | | `esperar` | `ECUAFACT_ESPERAR` | Con `true`, todos los `emitir` esperan el resultado del SRI. | | `descargar` | `ECUAFACT_DESCARGAR` | Archivos a descargar al autorizarse en todos los `emitir`; también activa la espera. | | `validarAntes` | `ECUAFACT_VALIDAR_ANTES` | Con `true`, todos los `emitir` y `vigilar` validan cada comprobante en la API antes de emitirlo. Por defecto, `false`. | Además, `ECUAFACT_API_KEY` define la API Key y tiene prioridad sobre la guardada, `ECUAFACT_API_URL` cambia la URL de la API ([Cambiar de ambiente o de URL](#cambiar-de-ambiente-o-de-url)) y `ECUAFACT_PERFIL` elige el perfil. `ECUAFACT_MAX_RESPUESTA_BYTES` cambia el tamaño máximo, en bytes, de una respuesta de la API (por defecto, 64 MiB); `0` quita el tope. Si una respuesta lo supera, el comando termina con un error que lo indica. ### Precedencia y ecuafact.json Cada valor sale del primero que lo defina, en este orden: 1. La opción del comando (`--entorno`, `--salida`, `--perfil`). 2. La variable de entorno `ECUAFACT_*`. 3. Un archivo `ecuafact.json` en la carpeta actual o en una superior, hasta la raíz Git más próxima o tu carpeta de usuario. Sin ninguno de esos límites, solo se consulta la carpeta actual. 4. Tu perfil (`config poner`). 5. El valor por defecto. `ecuafact.json` fija la configuración de un proyecto y se puede guardar en tu repositorio, porque nunca lleva la API Key. Como tiene prioridad sobre tu perfil, si `config poner` parece no tener efecto, revisa si hay uno con `ecuafact config ver`. Usa solo una configuración de proyecto de confianza. Antes de ejecutar comandos en un repositorio clonado, revisa su archivo de configuración y los valores efectivos. `carpetaDescargas` puede indicar una carpeta fuera del repositorio; el límite de búsqueda del archivo no restringe el destino de las descargas. Para elegir otra carpeta en un comando usa `--destino`. `--salida` cambia el formato de presentación, no la carpeta. ```json { "perfil": "empresa-b", "entorno": "sandbox", "ruc": "0123456789001", "salida": "json" } ``` ## Otros comandos | Comando | Descripción | |---|---| | `api [--datos @archivo] [--idempotency-key ] [--archivo-salida ]` | Llama a cualquier ruta de la API con tu API Key y muestra la respuesta tal cual. `` acepta `GET`, `POST` o `PUT`. Para emitir, pasa una `--idempotency-key` estable (`auto` genera una nueva en cada llamada). `--archivo-salida` es necesario para PDF y XML. | | `schema [comando]` | Describe el CLI en JSON, para scripts y agentes de IA. | | `docs [tema] [--imprimir]` | Abre esta documentación en el navegador; con `--imprimir`, solo muestra la URL. | | `ayuda [tema]` | Muestra guías breves que funcionan sin conexión. | ## Códigos de salida | Código | Significado | |---|---| | `0` | El comando terminó bien. | | `1` | Error general, de red o del servidor, o el comprobante quedó en `error`. | | `2` | Uso incorrecto del comando. | | `3` | Falló la autenticación, la IP o el permiso, o el comprobante quedó en `rechazo_configuracion` por la firma, la configuración del emisor o la suscripción. | | `4` | Error de validación, o el comprobante quedó `rechazado` por su contenido, con el `codEstado` 3002 (`comprobante_invalido`). | | `5` | El SRI rechazó el comprobante: quedó `rechazado` con el `codEstado` 3001 (`rechazo_sri`). | | `6` | Se superó el límite de solicitudes o no hay cupo, ya sea porque la API respondió 429 o porque el comprobante quedó en `rechazo_configuracion` con el `codEstado` 4004 (`cupo_agotado`). | | `7` | Resultado parcial: unos elementos salieron bien y otros no. | | `8` | No encontrado o en conflicto, o el comprobante quedó `cancelado`, con el `codEstado` 6001 (`operacion_cancelada`). | Cuando el código viene del resultado de un comprobante, depende de su `estado` y de su `codEstado`: | `estado` | `codEstado` | Código de salida | |---|---|---| | `autorizado` o `recibido` | 2001, 1001 o 1002 | `0` | | `rechazado` | 3001 (`rechazo_sri`) | `5` | | `rechazado` | 3002 (`comprobante_invalido`) | `4` | | `rechazo_configuracion` | 4001 (`emisor_no_configurado`), 4002 (`firma_no_valida`) o 4003 (`suscripcion_inactiva`) | `3` | | `rechazo_configuracion` | 4004 (`cupo_agotado`) | `6` | | `error` | 5006 (`entrega_no_posible`), 5007 (`resultado_no_confirmado`) o 5001 (`error_interno`) | `1` | | `cancelado` | 6001 (`operacion_cancelada`) | `8` | En los comandos que procesan varios elementos, el código resume el lote. En `emitir` y `lote reanudar` es 0 si ningún comprobante falló, 7 si unos salieron bien y otros no, y el código del primer fallo si ninguno salió bien (por ejemplo, 5 si el SRI rechazó todos). El 0 incluye los comprobantes en `recibido`, que todavía no tienen un resultado final, así que no los des por autorizados: usa `--esperar` o revisa el estado de cada uno con `--reporte`. `vigilar --una-vez` sigue el mismo criterio con los archivos de la carpeta, y `descargar` devuelve 7 si solo fallaron algunas descargas. Si la API no responde, o responde 500, 502, 503 o 504, o 429 con el `codEstado` 5005 (`limite_solicitudes`), el CLI repite la petición por su cuenta hasta tres veces, con una espera entre intentos y respetando la cabecera `Retry-After` cuando viene. Al emitir, cada reintento lleva la misma `Idempotency-Key`, así que no duplica el comprobante: si la primera solicitud se aceptó, recibes el mismo `idOperacion`. Si el error persiste después de los reintentos, el comando termina con su código de salida, 1 para los errores del servidor y 6 para el límite de solicitudes, y puedes reanudar el lote más tarde con `ecuafact lote reanudar`. Un 429 con el `codEstado` 4004 (`cupo_agotado`) no se reintenta, porque esperar no devuelve cupo. Cuando el CLI no se ejecuta en una terminal, por ejemplo desde un script, escribe el resultado en JSON por la salida estándar y los errores, también en JSON, por la salida de errores. Un error de la API se ve así: ```json { "error": "Credenciales inválidas.", "estadoHttp": 401, "estado": "rechazado", "codEstado": 3009, "idCorrelacion": "0HN7A2B3C4D5E:00000001", "codigoSalida": 3, "sugerencia": "Revisa la API Key ('ecuafact sesion') y, en produccion, que la IP publica de este equipo este registrada en el portal (Cuenta > IP permitidas). 'ecuafact doctor' muestra la IP detectada." } ``` | Campo | Descripción | |---|---| | `error` | Mensaje del error. | | `codigoSalida` | El mismo código con el que termina el comando. | | `sugerencia` | Qué hacer, cuando el CLI lo sabe. | | `estadoHttp`, `estado`, `codEstado` | Solo si el error vino de la API: el estado HTTP, el `estado` y el [`codEstado`](/v1/guias/errores#catalogo-de-codestado) del cuerpo de error. | | `errores` | Solo si la API devolvió detalle de validación. | | `idCorrelacion` | Solo si el error vino de la API. Inclúyelo si escribes a soporte. | ## Siguientes pasos - [CLI de Ecuafact](/v1/guias/cli): instala el CLI y emite tu primera factura. - [Emitir con el CLI](/v1/guias/cli-emision): emite lotes y carpetas y descarga sus archivos. --- # Continuidad y salida Qué disponibilidad esperar, cómo se comparte tu cupo, cuánto tiempo conservamos tus documentos y cómo recuperarlos si dejas de usar el servicio. Antes de integrar un servicio de facturación en tu sistema es razonable preguntar qué pasa si el servicio falla, cuánto cuesta quedarte sin cupo y cómo te llevas tus documentos si algún día decides irte. Esta página responde esas preguntas con lo que puedes comprobar como integrador, para que las incluyas en tu evaluación y en el diseño de tu sistema. Al terminar sabrás qué objetivo de disponibilidad tenemos, cómo protegerte de un cupo agotado, cuánto tiempo conservamos tus documentos y qué pedir a soporte para recuperarlos. ## Disponibilidad Nuestro objetivo de disponibilidad de la API en producción es de 99,9 % mensual. Se mide sobre la recepción y el procesamiento de tus comprobantes. La autorización del SRI es una dependencia externa y no forma parte de este objetivo. Es un objetivo de servicio y no una garantía contractual; si tu organización necesita una cláusula formal, pídela a soporte antes de contratar. Puedes revisar el estado del servicio en cualquier momento en la [página de estado](/v1/estado), que muestra la disponibilidad de los últimos 90 días y los incidentes. Los mismos datos están en `GET /estado`, sin API Key, para que los consultes desde tus propias alertas; la guía [Estado del servicio](/v1/guias/estado-del-servicio) explica el formato y el límite de consultas. Si tu sistema recibe un 503 con el `codEstado` 5002 (`servicio_no_disponible`), espera los segundos que indica `Retry-After` y reenvía el mismo comprobante con la misma `Idempotency-Key`: así no se duplica aunque la primera petición haya llegado. El detalle de qué errores se reintentan está en [Buenas prácticas](/v1/guias/buenas-practicas) y en [Errores](/v1/guias/errores). | Compromiso | Valor | |---|---| | Objetivo de disponibilidad de la API en producción | 99,9 % mensual | | Autorización del SRI | Dependencia externa; se informa por separado | | Atención de soporte | Lunes a viernes, de 09:00 a 18:00 (GMT-5) | | Primera respuesta | 1 día hábil | | Primera respuesta si producción está caída | 4 horas | | Canales | [Ticket](https://soporte.ecuafact.com/), [centro de ayuda](https://ecuafact.com/ayuda/), [WhatsApp](https://wa.me/593988315544) y [contacto](https://ecuafact.com/contacto) | ## Seguridad de tus llaves Cada API Key tiene dos límites que defines tú al crearla: los servicios que puede usar y los RUC sobre los que puede actuar. Una llave limitada a un RUC no puede emitir ni consultar a otro contribuyente, y una llave comprometida solo da acceso a lo que le asignaste. Además, en producción la API solo acepta peticiones desde las IP que registraste. Si sospechas que una llave se filtró, crea otra, cámbiala en tu sistema y revoca la anterior; la revocación se aplica en un máximo de 30 segundos. Los pasos están en [Autenticación](/v1/guias/autenticacion#rota-o-revoca-una-api-key), y cómo limitar una llave, en [Scopes y RUC de una API Key](/v1/guias/autenticacion#scopes-y-ruc-de-una-api-key). ## Cupo Tu [cupo](/v1/guias/glosario#cupo) se comparte entre todos los RUC de tu integración. No existe un reparto por RUC: si emites para varios contribuyentes, todos descuentan del mismo saldo, y uno que emite mucho puede agotar el de los demás. Consumen cupo los comprobantes que terminan autorizados o rechazados por el SRI; un comprobante cancelado no consume cupo. El detalle por estado está en [Consumo y cuotas](/v1/guias/consumo). > [!WARNING] > Si tu cupo se agota, la emisión de todos tus RUC se detiene hasta que renueves o compres un paquete. Controla tu saldo desde tu propio sistema. | Situación | Respuesta de la emisión | Qué hacer | |---|---|---| | Te quedan documentos | 202 Accepted | Sigue emitiendo. | | No te quedan documentos | 429 con el `codEstado` 4004 (`cupo_agotado`) | Compra un paquete; no reintentes. | Consulta tu saldo con [`GET /v1/consumo`](/v1/guias/consumo) antes de enviar un lote grande y configura una alerta en tu sistema para avisar a tu equipo cuando queden pocos documentos. ## Conservación de tus documentos Conservamos tus comprobantes durante siete años, el plazo que exige la normativa tributaria del SRI. En ese tiempo puedes descargar el XML y el RIDE de cualquier comprobante con su clave de acceso y consultar el historial de operaciones. | Qué necesitas | Cómo lo obtienes | |---|---| | Un comprobante | [Descarga el XML](/v1/guias/consulta-xml) o el [RIDE](/v1/guias/consulta-ride) con su clave de acceso. | | Los comprobantes de un período | Usa el [listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente) o el comando `ecuafact operaciones listar`. | | Todos tus documentos | Solicita una exportación masiva a soporte. | ## Exportación masiva Si necesitas llevarte todos tus documentos, por ejemplo para un respaldo, una auditoría o un cambio de proveedor, abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/). Escribe desde el correo registrado del titular de la cuenta o del contribuyente, e indica el RUC, el rango de fechas y los tipos de comprobante que necesitas. Te entregamos la exportación en un plazo de 5 días hábiles desde que verificamos tu solicitud. Si el volumen es grande, acordamos contigo otro plazo al recibirla. La primera exportación no tiene costo. La exportación llega como un archivo comprimido con esta estructura: | Contenido | Descripción | |---|---| | Una carpeta por RUC | Dentro de cada una, el XML y el RIDE de cada comprobante, nombrados con su clave de acceso. | | Un archivo CSV de índice | Una fila por comprobante, con la clave de acceso, el tipo, el número, la fecha, el estado y el total. | | Un archivo de sumas de verificación | El SHA-256 de cada archivo, para que compruebes que no se alteró. | Te enviamos un enlace de descarga privado que vence a los pocos días; nunca enviamos los documentos como adjuntos de correo. ## Si terminas tu contrato No eliminamos tus documentos cuando termina tu contrato: te los entregamos. Solicítalos a soporte y recibirás tu archivo completo de comprobantes. Para que tu salida sea sencilla, ten presente lo siguiente: - Tu certificado de firma electrónica pertenece al contribuyente. - Si envías tu propio `secuencial` en cada comprobante, tu numeración es tuya. Si lo omites y lo asignamos nosotros, consulta el último número de cada serie en el listado de operaciones o pídelo a soporte para continuarlo en tu nuevo sistema. - Guarda en tu sistema el XML autorizado y la clave de acceso de cada comprobante, como recomienda [Descargar XML](/v1/guias/consulta-xml#cuando-usarlo). ## Siguientes pasos - [Límite de request](/v1/guias/limite-de-request): conoce cuántas solicitudes por minuto puedes hacer. - [Consumo y cuotas](/v1/guias/consumo): consulta cuántos documentos te quedan. - [Autenticación](/v1/guias/autenticacion): limita tus llaves por servicio y RUC. - [Estado del servicio](/v1/guias/estado-del-servicio): consulta la disponibilidad actual y los incidentes. --- # Colecciones Descarga la colección de Postman y los ejemplos de la API para probar cada petición sin escribir código, también desde Bruno o Newman. Antes de escribir código, puede servirte ver cómo responde la API a cada petición. Con nuestra colección de Postman puedes enviar las peticiones principales del contrato tal como vienen, con pruebas automáticas que comprueban la respuesta, y también puedes abrirla en Bruno o ejecutarla desde la terminal con Newman. En esta página encontrarás todos los archivos descargables, cómo configurar la colección con tu API Key de pruebas y cómo emitir tu primera factura desde Postman, además de qué contiene cada carpeta y cómo usarla en Bruno y Newman. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. El environment apunta a > `https://api-sandbox.mynexusapi.com`. ## Archivos La colección y el environment también están publicados en el workspace público de Postman [Ecuafact API](https://www.postman.com/ecuafact/ecuafact-api). Desde ahí puedes hacer un *fork* a tu propio workspace y recibir las actualizaciones sin descargar ni importar archivos. | Archivo | Contenido | |---|---| | [Colección Postman](/downloads/v1/Ecuafact-API-v1.postman_collection.json) | Las peticiones del flujo de integración, agrupadas por carpeta, con pruebas automáticas y scripts que generan la fecha de emisión y la `Idempotency-Key`. Formato Postman v2.1; Bruno y Newman la importan. | | [Environment](/downloads/v1/Ecuafact-API.postman_environment.json) | Variables `baseUrl` (pruebas), `baseUrlProduccion`, `apiKey` (vacía), `identificacion`, `ruc`, `estab`, `ptoEmi`, `claveAcceso` (de ejemplo, para decodificar), `idOperacion` más `idOperacion01` a `idOperacion07` (se llenan solas al emitir), `claveAccesoEmitida` (se llena sola cuando la operación queda autorizada), `idDestino` (se llena al crear o listar destinos) y `eventoId` (se llena al listar entregas). | | [OpenAPI](/api/openapi.json) | Especificación OpenAPI 3.1 de la API. Importable en Postman, Bruno, Insomnia o generadores de clientes. | | Ejemplos de solicitud | Un JSON listo por tipo de comprobante: [Factura `01`](/downloads/v1/ejemplos/example-01.json), [Liquidación de compra `03`](/downloads/v1/ejemplos/example-03.json), [Nota de crédito `04`](/downloads/v1/ejemplos/example-04.json), [Nota de débito `05`](/downloads/v1/ejemplos/example-05.json), [Guía de remisión `06`](/downloads/v1/ejemplos/example-06.json) y [Retención `07`](/downloads/v1/ejemplos/example-07.json). | | [Emisión para asistentes](/downloads/v1/emision-factura.md) | Resumen corto del contrato de emisión para pegar en un asistente de IA. | | [Catálogo de servicios](/.well-known/api-catalog) | Enlaces a OpenAPI, documentación y versiones (RFC 9727), para descubrimiento automático. | | [Versiones del contrato](/.well-known/api-versions.json) | Versión vigente, fechas y retiro, en JSON. | | [llms.txt](/llms.txt) y [llms-full.txt](/llms-full.txt) | Índice y texto completo de la documentación para asistentes de IA. | Los ejemplos JSON usan el contribuyente 0123456789001 de [Datos de prueba](/v1/guias/datos-de-prueba) y el `secuencial` `"000000000"`, con el que te asignamos el siguiente. Antes de enviarlos, cambia `infoTributaria.ruc` por tu RUC y `fechaEmision` por la fecha de hoy, en formato `dd/MM/yyyy`. Las referencias a documentos de sustento de los tipos 04, 05 y 07 son de ejemplo, así que reemplázalas por comprobantes tuyos. ## Requisitos - [ ] [Postman](https://www.postman.com/downloads/) o [Bruno](https://www.usebruno.com/) instalado. Para la terminal, instala Newman con `npm install -g newman`. - [ ] Una API Key de pruebas. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox). - [ ] Tu `identificacion`, que es tu RUC de 13 dígitos. La ves en `GET /v1/contexto` o en el portal del cliente. - [ ] La IP de tu equipo registrada, solo si trabajas en producción: el sandbox acepta llamadas desde cualquier IP, y en producción la registras en **Cuenta > IP permitidas**. ## Usar la colección en Postman Sigue estos pasos para emitir tu primera factura desde Postman: 1. Descarga los dos archivos, la colección y el environment. 2. En Postman, pulsa **Import** y arrastra ambos archivos. Aparecen la colección `Ecuafact API — Comprobantes Electronicos SRI (v1)` y el environment `Ecuafact API — Plantilla`. 3. Arriba a la derecha, en el selector de environments, elige `Ecuafact API — Plantilla`. Sin un environment seleccionado, la colección usa sus propias variables, que apuntan a pruebas pero con `apiKey` vacía, así que las peticiones autenticadas responden 401. 4. Abre el environment con el icono del ojo y **Edit**, y completa estas variables: - `apiKey`: tu API Key. Márcala como tipo **secret** para que no se vea. - `identificacion`: tu `identificacion` de `GET /v1/contexto`, que es tu RUC de 13 dígitos. - `ruc`: el mismo valor de `identificacion`. - `estab` y `ptoEmi`: tu establecimiento y punto de emisión. La plantilla trae `002` y `001`; cámbialos por los de tu contribuyente. Guarda con **Save**. 5. Ejecuta **00 > 00.2 Contexto de la credencial**. Funcionó si la respuesta es 200 y lista tus contribuyentes. Un 401 con el `codEstado` 3009 (`credenciales_invalidas`) indica que falta la API Key o no es válida. Un 403 con el `codEstado` 3010 (`ip_no_autorizada`) indica que la IP no está permitida. 6. Si quieres comprobar la factura antes de emitirla, ejecuta **01 > 01.0 Validar factura (sin emitir)**. Envía el mismo cuerpo que 01.1 y responde 200 con `valido` en `true` y `errores` vacío cuando la factura es válida, o 422 con el `codEstado` 3002 (`comprobante_invalido`) y el problema en `errores` cuando no lo es. Esta petición no emite nada, no consume cupo ni lleva `Idempotency-Key`, así que puedes repetirla las veces que necesites; lo explica [Validar sin emitir](/v1/guias/emision#validar-sin-emitir). 7. Ejecuta **01 > 01.1 Factura**. Deberías recibir `202 Accepted` con `estado` `recibido`, un `codEstado` 1001 o 1002 y un `idOperacion`, que la prueba de la petición guarda en el environment. 8. Ejecuta **02 > 02.1 Ver operación** varias veces, con unos segundos de espera entre cada una, mientras `estado` sea `recibido`. Termina en `autorizado`, o en `rechazado` con el `codEstado` 3001 (`rechazo_sri`) si el SRI lo rechazó. Cuando queda `autorizado`, la prueba de la petición guarda la `claveAcceso` en `claveAccesoEmitida`. 9. Ejecuta **06 > 06.1 Descargar RIDE (PDF)** para bajar el PDF de esa factura. En Postman, guárdalo con **Save Response > Save to a file**. 10. Para conciliar lo emitido, abre **03 > 03.1 Listar operaciones** y ajusta `desde` y `hasta` al período. La petición usa tu `identificacion` y devuelve la página con `comprobantes`, `pagina`, `tamanoPagina` y `hayMas`. 11. Para administrar webhooks, usa la carpeta **08**. Empieza por **08.1 Crear destino** o **08.2 Listar destinos**: la prueba guarda el `publicId` en `idDestino` para las demás peticiones. Copia el `secretoUnaVez` de la respuesta a tu servidor; la colección no lo guarda ni lo imprime. Cada petición de emisión genera con un script una `Idempotency-Key` y una `referenciaExterna` nuevas, así que repetirla emite un comprobante nuevo con el siguiente secuencial. Para probar el reintento idempotente, reemplaza en la petición la cabecera `Idempotency-Key` (`{{idempotencyKey}}`) y el valor de `referenciaExterna` del cuerpo (`{{referenciaExterna}}`) por valores fijos tuyos, y envíala dos veces el mismo día. La segunda respuesta es igual a la primera y trae el mismo `idOperacion`. Si fijas solo la `Idempotency-Key`, el cuerpo cambia y la segunda respuesta es un 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Las peticiones de emisión traen deshabilitada la cabecera opcional `X-Additional-Info`, con el valor `MiERP/4.2 sucursal=001`. Actívala y cambia el valor por el nombre y la versión de tu sistema para que soporte encuentre tus solicitudes; la cabecera no cambia la respuesta. Sus reglas están en [Límites](/v1/guias/limites#cabeceras). ## Qué hay en cada carpeta La colección agrupa las peticiones en carpetas numeradas, en el orden en que las usarías al integrar. | Carpeta | Peticiones | Para qué | |---|---|---| | `00` Inicio y diagnóstico | Salud del servicio (`GET /salud`, sin API Key), contexto, cupo, estado del servicio (`GET /estado`, sin API Key) | Comprobar conexión, API Key y cupo antes de emitir. | | `01` Emitir comprobantes | Validar factura (sin emitir), factura, liquidación, nota de crédito, nota de débito, guía de remisión, retención | Comprobar una factura antes de emitirla y luego una emisión por tipo; cada emisión guarda su `idOperacion`. | | `02` Seguimiento de operación | Ver operación | Consultar el resultado del SRI de la última emisión. | | `03` Listado de operaciones | Listar operaciones | Consultar los comprobantes de un contribuyente y un período, con filtros y paginación. | | `04` Errores y casos límite | 401 sin credencial, 400 sin `Idempotency-Key`, 422 campo no soportado, 422 XML con `codDoc` incorrecto y 429 cupo agotado | Ver la forma de cada error. El caso de cupo agotado solo responde 429 si tu cupo está realmente agotado. | | `05` Consultas SRI | Contribuyente, búsqueda por nombre, establecimientos, validar identificación, decodificar clave | Consultas al catastro del SRI; no consumen cupo. | | `06` Descargas | Descargar RIDE (PDF), descargar XML | Obtener los archivos de un comprobante emitido. Usan `claveAccesoEmitida`. | | `07` Perfil del emisor | Leer perfil, actualizar perfil, cambiar logo | Ver y cambiar los datos del emisor que salen en el RIDE. La actualización y el logo cambian el perfil real del ambiente donde los ejecutes. | | `08` Webhooks | Crear destino, listar destinos, pausar, reanudar, rotar secreto, entregas, reintentar y deshabilitar | Administrar los destinos por API. Crear y rotar devuelven el secreto una sola vez; la colección no lo guarda. | | `09` Catálogos | Listar catálogos, leer un catálogo | Consultar los catálogos del SRI con `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}`; la variable `catalogo` elige la clave y vale `tarifas-iva` por defecto. | Las carpetas `03`, `08` y `09` no forman parte del flujo de emisión: ejecútalas cuando necesites conciliar comprobantes, administrar destinos o leer los catálogos. La carpeta `08` crea, pausa o deshabilita destinos reales en el ambiente donde la ejecutes. ## Usar la colección en Bruno Si prefieres Bruno, puedes importar en él la colección de Postman. Para usarla, sigue estos pasos: 1. En Bruno, elige **Import Collection** > **Postman Collection** y selecciona el archivo de la colección. Bruno te pide una carpeta para guardarla. 2. En la colección, abre **Environments** > **Create** y crea un environment con las variables `baseUrl` (`https://api-sandbox.mynexusapi.com`), `apiKey` (márcala como secreta), `identificacion`, `ruc`, `estab` y `ptoEmi`. 3. Selecciona ese environment y sigue los pasos 5 a 9 de Postman. Bruno ejecuta los scripts de Postman más comunes. Si una prueba automática no corre, la petición se envía igual y puedes leer la respuesta. ## Ejecutar con Newman Si necesitas ejecutar la colección desde la terminal, por ejemplo en un proceso de integración continua, puedes usar Newman. Pasa la API Key por variable de entorno, para no guardarla en el archivo: ```bash newman run Ecuafact-API-v1.postman_collection.json \ -e Ecuafact-API.postman_environment.json \ --env-var "apiKey=$ECUAFACT_API_KEY" \ --env-var "identificacion=0123456789001" \ --env-var "ruc=0123456789001" ``` Newman imprime cada petición con su estado y las pruebas que pasaron o fallaron. Al ejecutar la carpeta `01` se emiten comprobantes de prueba y se consume cupo del sandbox. Si ejecutas la colección completa, ten en cuenta que **07.2** y **07.3** cambian el perfil del emisor, y que la carpeta **08** crea, pausa, reanuda, rota el secreto o deshabilita destinos reales del ambiente. Para dejarlas fuera, ejecuta solo las carpetas que necesitas con `--folder`. ## Siguientes pasos - [Primeros pasos](/v1/guias/primeros-pasos): sigue el mismo flujo paso a paso, con código. - [Datos de prueba](/v1/guias/datos-de-prueba): usa los valores de ejemplo y los casos de prueba para provocar cada respuesta. - [SDKs](/v1/guias/sdk): pasa de la colección a código con un cliente oficial. --- # Privacidad de la medición Esta página explica qué medimos cuando navegas esta documentación, para qué lo usamos y cómo puedes aceptar o rechazar la medición en cualquier momento. Medimos el uso de esta documentación para saber qué páginas se consultan, qué ejemplos se copian y dónde se atascan quienes quieren integrarse, y así mejorarla. La medición es nuestra, no usa servicios de terceros y solo empieza si la aceptas en el aviso que verás la primera vez que entras. Mientras no aceptes, no guardamos nada en tu navegador salvo tu decisión y no enviamos ninguna información a nuestros servidores. En esta página verás qué datos recogemos, cuáles nunca guardamos, cuánto tiempo los conservamos y cómo cambiar tu decisión. ## Qué medimos Si aceptas la medición, registramos qué haces dentro de la documentación, siempre asociado a un identificador aleatorio que se guarda en tu navegador y que no está ligado a tu nombre, tu correo ni tu cuenta. - Las páginas que visitas, desde qué página de la documentación llegaste a ellas y hasta dónde las lees (la mitad y casi el final). - Los ejemplos de código y los prompts para agentes que copias, el lenguaje de programación que eliges en los ejemplos y el tema claro u oscuro que usas. - Los términos que escribes en el buscador, con los correos y las secuencias de seis o más dígitos reemplazados por una marca y recortados a 80 caracteres. - Las descargas que haces (la especificación OpenAPI, las colecciones de Postman, el skill) y los enlaces a sitios externos que abres, como los paquetes de los SDK. - Los clics en los enlaces para crear tu cuenta de pruebas o de producción. Si creas la cuenta desde uno de esos enlaces, relacionamos el alta con tu visita para saber cuántas cuentas nacen de esta documentación. No incluimos en la medición ningún dato de tu cuenta ni de tu empresa. - Datos generales de tu equipo: si usas un computador, un celular o una tableta, la familia de tu navegador y de tu sistema operativo, tu idioma, el país aproximado desde el que te conectas y el sitio desde el que llegaste, junto con los parámetros de campaña de ese enlace si los trae. ## Qué no guardamos No guardamos tu dirección IP ni la identificación completa de tu navegador. Tampoco guardamos nombres, correos, teléfonos, números de identificación, claves ni el contenido de lo que pegas o escribes fuera del buscador. Si tu navegador envía la señal de no rastrear o el control global de privacidad, la tratamos como un rechazo: no te mostramos el aviso y no medimos nada. ## Para qué lo usamos Usamos la información para decidir qué guías mejorar, qué ejemplos completar y qué rutas de integración necesitan más ayuda, y para entender cuántas cuentas de pruebas se crean después de leer la documentación. No la usamos para identificarte ni para enviarte mensajes, y no la compartimos con terceros. ## Cuánto tiempo la conservamos Conservamos el detalle de cada visita durante 90 días. Pasado ese plazo lo eliminamos y solo quedan cifras agregadas por día, sin identificadores, que nos sirven para ver la evolución del uso. ## Cómo cambiar tu decisión Puedes aceptar o rechazar la medición cuando quieras desde el enlace **Preferencias de medición**, que está al pie de cada página de la documentación. Al rechazarla, borramos de tu navegador el identificador y todo lo que guardó la medición, y dejamos de enviar información. Si prefieres que eliminemos la información de una visita anterior, escríbenos a [soporte](https://soporte.ecuafact.com/) e indícanos desde qué navegador entraste. ## Política general de Ecuafact Los términos del servicio y el tratamiento de datos personales de Ecuafact están en [legal.ecuafact.com](https://legal.ecuafact.com/). ## Siguientes pasos - Si todavía no tienes una cuenta, crea tu [sandbox de pruebas](/v1/guias/sandbox) y emite tu primer comprobante con los [primeros pasos](/v1/guias/primeros-pasos). - Si necesitas ayuda con tu integración, revisa las [preguntas frecuentes](/v1/guias/faq) o abre un ticket en [soporte](https://soporte.ecuafact.com/). --- # 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). --- # 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: ```text 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](#permisos) que le des. - **Sobre qué RUC.** Puede trabajar con todos los [contribuyentes](/v1/guias/glosario) 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](#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](#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. > [!IMPORTANT] > 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`](/v1/guias/errores#catalogo-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](/v1/guias/errores#codigos-de-resultado-de-una-operacion), 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](/v1/guias/colecciones). | Para conectarlo en Claude Code: ```bash 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](/v1/guias/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: ```bash 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. ```json { "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**. ```json { "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. ```json { "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`: ```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](/v1/guias/consulta-contexto). 3. Si ves un error, búscalo en [Errores](#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**. > [!WARNING] > 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. ```bash 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: ```json { "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: ```bash 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](/v1/guias/consulta-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`: ```python 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`: ```javascript 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`: ```csharp 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 { ["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 { ["Authorization"] = "Bearer " + token } }); await using McpClient cliente = await McpClient.CreateAsync(transporte); CallToolResult resultado = await cliente.CallToolAsync("obtener_contexto", new Dictionary()); Console.WriteLine(((TextContentBlock)resultado.Content[0]).Text); ``` En PHP, el bot pide el token y llama a la herramienta directamente por HTTP: ```php 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](#documentacion) | | 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](#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](#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](#confirmacion-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](/v1/guias/consumo) 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](/v1/guias/consulta-operacion) 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](/v1/guias/consulta-ride) (PDF) o el [XML](/v1/guias/consulta-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](/v1/guias/consulta-identificacion) sin consultar al SRI; revisa `valido`. | | `consultar_contribuyente` | `identificacion` (cédula, RUC o pasaporte) | `GET /v1/consultas/contribuyentes/{identificacion}` | [Datos del catastro](/v1/guias/consulta-contribuyente) 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](/v1/guias/consulta-contribuyente-nombre) 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](/v1/guias/consulta-establecimientos) de un RUC. | | `decodificar_clave_acceso` | `claveAcceso` (49 dígitos) | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | [Separa la clave](/v1/guias/consulta-clave-acceso) 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](#servidor-de-documentacion), 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`](/v1/guias/errores#catalogo-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](/v1/guias/emision#validar-sin-emitir) 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](/v1/guias/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](/v1/guias/perfil-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](/v1/guias/emision) 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](/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) y [Comprobante de retención](/v1/guias/emision-07). ### 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." > [!WARNING] > 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 '': `: | 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]: ` | 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 [codEstado ]: Errores: ; ` (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 (). 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 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](#confirmacion-en-el-portal) 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](#documentacion) 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](#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](/v1/guias/errores). ## Skill Puedes complementar el MCP con nuestro [skill para asistentes](/v1/guias/skill), que le enseña a tu asistente a construir comprobantes correctos, con los campos, los códigos del SRI y las reglas de cálculo. Con el skill, el asistente sabe qué enviar, y con el MCP lo envía por ti. ## Siguientes pasos - [Skill para asistentes de IA](/v1/guias/skill): instala el conocimiento de la API en tu asistente. - [Instrucciones para agentes](/v1/guias/agentes): revisa el resumen del contrato y las reglas que debe seguir un agente. - [Factura](/v1/guias/emision-01): conoce la estructura que el asistente envía en `estructura`. --- # Skill para asistentes de IA Descarga el skill de Ecuafact para que Claude Code, Copilot, Cursor u otro agente conozca la API y genere integraciones correctas. Si programas con un asistente de IA, puedes darle el conocimiento de nuestra API con nuestro skill, para que escriba la integración contigo sin inventar campos ni códigos. El skill es un paquete de archivos markdown con lo que el asistente necesita saber, desde la autenticación hasta los campos de cada tipo de comprobante. En esta página descargas el skill, lo instalas en la carpeta de tu asistente y compruebas que lo está usando. Al final verás cómo mantenerlo al día cuando cambia el contrato. ## Conceptos Un **skill** es una carpeta con un archivo `SKILL.md`, que contiene las instrucciones y el mapa de recursos, y con archivos de referencia que el asistente lee solo cuando los necesita. Sigue el estándar abierto **Agent Skills**, así que es markdown portable, no depende de un proveedor de IA y no ejecuta nada por sí mismo. Las instrucciones del skill están en inglés, que es el idioma en que los asistentes siguen mejor las indicaciones, pero todo lo que forma parte del contrato se mantiene en español, tal como lo recibe la API: nombres de campos, rutas, códigos de error, mensajes y valores de catálogo. El asistente te responde en el idioma en que le escribes, y el código que genera usa los nombres exactos del contrato. Con el skill, tu asistente aprende cómo se integra la API y te ayuda a escribir el código. Si además necesitas que consulte o emita comprobantes por ti, puedes conectarlo a nuestro [servidor MCP](/v1/guias/mcp), con los permisos que le des al conectarlo. ## Requisitos - [ ] Un asistente compatible con Agent Skills, como Claude Code, GitHub Copilot, Cursor u otro agente que cargue carpetas con `SKILL.md`. - [ ] Opcionalmente, una API Key de pruebas, si quieres que el asistente, además de escribir código, lo ejecute contra el ambiente de pruebas. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox). ## Descarga [Descargar el paquete (`ecuafact.zip`)](/downloads/v1/skills/ecuafact.zip) El `.zip` contiene directamente `SKILL.md` y la carpeta `reference/`, sin una carpeta raíz que los agrupe. Esta tabla muestra qué trae cada archivo y cuándo lo lee el asistente: | Archivo | Contenido | El asistente lo lee cuando... | |---|---|---| | `SKILL.md` | Ambientes, autenticación, ciclo de vida, emisión, endpoints y mapa de recursos. | Siempre que el skill se activa. | | `reference/codigos-sri.md` | Tipos de identificación, IVA, formas de pago y retenciones. | Necesita un código exacto del SRI. | | `reference/emision/factura-01.md` | Campos y ejemplo de la factura. | Emites o validas una factura (`01`). | | `reference/emision/liquidacion-03.md` | Campos y ejemplo de la liquidación de compra. | Emites una liquidación (`03`). | | `reference/emision/nota-credito-04.md` | Campos y ejemplo de la nota de crédito. | Emites una nota de crédito (`04`). | | `reference/emision/nota-debito-05.md` | Campos y ejemplo de la nota de débito. | Emites una nota de débito (`05`). | | `reference/emision/guia-remision-06.md` | Campos y ejemplo de la guía de remisión. | Emites una guía de remisión (`06`). | | `reference/emision/retencion-07.md` | Campos y ejemplo del comprobante de retención. | Emites una retención (`07`). | | `reference/consultas.md` | Contexto, operación, cupo, RIDE/XML y perfil. | Consultas o descargas algo ya emitido. | | `reference/consultas-sri.md` | Contribuyente, establecimientos, validar identificación y decodificar clave. | Consultas el catastro del SRI. | | `reference/webhooks.md` | Eventos y sus `estado` y `codEstado`, firma, reintentos y verificación de webhooks. | Implementas el receptor de webhooks. | | `reference/errores-limites.md` | Catálogo de `codEstado` con "Qué hacer", límites y soporte. | Manejas errores o límites. | | `reference/herramientas.md` | SDK, CLI `ecuafact`, colección de Postman y servidores MCP. | Eliges cómo integrarte o usas una de esas herramientas. | Los ejemplos del skill usan los [datos de prueba](/v1/guias/datos-de-prueba) publicados. ## Instalación El skill también está publicado en GitHub, en [Ecuanexus/ecuafact-skill](https://github.com/Ecuanexus/ecuafact-skill). Si usas la CLI de skills, instálalo con un solo comando: ```bash npx skills add Ecuanexus/ecuafact-skill ``` Para instalarlo a mano con el `.zip`, sigue estos pasos: 1. Descarga `ecuafact.zip`. 2. Crea una carpeta llamada `ecuafact` dentro de la carpeta de skills de tu asistente, que encontrarás en la tabla siguiente. 3. Descomprime el `.zip` **dentro** de `ecuafact`, de modo que queden `ecuafact/SKILL.md` y `ecuafact/reference/...`. 4. Reinicia el asistente o abre una sesión nueva. | Asistente | Carpeta del skill | |---|---| | Claude Code (solo este proyecto) | `.claude/skills/ecuafact/` en la raíz del proyecto | | Claude Code (todos tus proyectos) | `~/.claude/skills/ecuafact/` | | GitHub Copilot en VS Code (solo este proyecto) | `.github/skills/ecuafact/` en la raíz del proyecto | | Cursor y otros agentes compatibles con Agent Skills | La carpeta de skills que indique la documentación de tu herramienta, con la misma estructura `ecuafact/SKILL.md` + `ecuafact/reference/` | En Linux o macOS, estos comandos instalan el skill para Claude Code en el proyecto actual: ```bash mkdir -p .claude/skills/ecuafact curl -sL https://docs.mynexusapi.com/downloads/v1/skills/ecuafact.zip -o ecuafact.zip unzip -o ecuafact.zip -d .claude/skills/ecuafact ls .claude/skills/ecuafact # debe mostrar SKILL.md y reference ``` En Windows, estos son los mismos comandos en PowerShell: ```powershell New-Item -ItemType Directory -Force .claude\skills\ecuafact | Out-Null Invoke-WebRequest https://docs.mynexusapi.com/downloads/v1/skills/ecuafact.zip -OutFile ecuafact.zip Expand-Archive ecuafact.zip -DestinationPath .claude\skills\ecuafact -Force Get-ChildItem .claude\skills\ecuafact # debe mostrar SKILL.md y reference ``` Para otro asistente, cambia `.claude/skills/ecuafact` por la carpeta que indica la tabla. ### Verifica la instalación Pregunta al asistente: "Con el skill de ecuafact, ¿qué cabeceras necesito para emitir una factura?". La instalación funcionó si responde `X-Api-Key`, `Idempotency-Key` y `Content-Type: application/json`, y si menciona que la respuesta es `202 Accepted`. En Claude Code también puedes comprobar que el skill aparece en la lista de skills disponibles. ## Mantenerlo actualizado El skill es una copia de la documentación tal como estaba al momento de la descarga. Cuando el [changelog](/v1/guias/changelog) registre un cambio de contrato, descarga el paquete de nuevo y reemplaza la carpeta completa. Borra la carpeta anterior antes de descomprimir, para no dejar archivos sobrantes. Si tu asistente tiene acceso a internet, también puede consultar la documentación vigente sin depender de la copia local: - [llms.txt](/llms.txt): índice de todas las guías con su descripción. - [llms-full.txt](/llms-full.txt): toda la documentación en un solo archivo. - Markdown por guía: agrega `.md` a la URL (por ejemplo, `/v1/guias/emision-01.md`) o pide la guía con `Accept: text/markdown`. Si el skill y la guía en línea difieren, la guía en línea es la vigente. ## Siguientes pasos - [MCP y asistentes](/v1/guias/mcp): conecta el asistente con OAuth para que consulte y emita con los permisos que le des. - [Instrucciones para agentes](/v1/guias/agentes): revisa el resumen del contrato y las reglas para agentes. - [Primeros pasos](/v1/guias/primeros-pasos): sigue paso a paso el flujo completo que describe el skill. --- # Instrucciones para agentes de IA Lo esencial del contrato de la API de Ecuafact y las reglas que debe seguir un agente de IA que integra o usa la facturación electrónica. Si configuras un agente de IA para trabajar con nuestros servicios de facturación, puedes darle esta página como punto de partida. Sirve para un asistente de programación que genera tu integración, un agente conectado a nuestro servidor MCP o un script que usa nuestro CLI. Si quieres un texto listo para pegar en tu agente, busca la sección «Para agentes» de las guías de [Primeros pasos](/v1/guias/primeros-pasos), [SDK](/v1/guias/sdk), [CLI](/v1/guias/cli) y [MCP](/v1/guias/mcp). Encontrarás el contrato en 15 líneas, los recursos pensados para agentes y cómo citarlos, lo que tu agente puede hacer con el MCP, el skill o el CLI, y las reglas que debe respetar siempre. ## Contrato en 15 líneas 1. La URL base de pruebas es `https://api-sandbox.mynexusapi.com` y la de producción, `https://api.mynexusapi.com`. El ambiente lo define la URL; nunca se envía en el cuerpo. 2. Toda llamada a `/v1` lleva la cabecera `X-Api-Key` y se hace solo desde el backend. Una API Key cubre todos los contribuyentes autorizados de la integración, y en producción la IP de origen debe estar registrada; si no lo está, la API responde 403 con el `codEstado` 3010 (`ip_no_autorizada`). El sandbox acepta cualquier IP. Una API Key ausente, inválida o revocada responde 401 con el `codEstado` 3009 (`credenciales_invalidas`). 3. El primer paso es `GET /v1/contexto`. `contribuyentes[].identificacion` es la identificación completa del contribuyente (su RUC de 13 dígitos o una identificación de 5 a 13 dígitos) y va igual en las rutas y en `infoTributaria.ruc`. 4. La emisión es `POST /v1/contribuyentes/{identificacion}/{ruta}` y el tipo lo fija la ruta: `facturas` (`01`), `liquidaciones-compra` (`03`), `notas-credito` (`04`), `notas-debito` (`05`), `guias-remision` (`06`) o `retenciones` (`07`), con `Content-Type: application/json` o `application/xml`. Si envías el XML del SRI, se aplican las mismas reglas que al JSON y la firma que traiga se ignora. El cuerpo admite como máximo 2 MiB. `POST /v1/contribuyentes/{identificacion}/{ruta}/validar` aplica las mismas reglas sin emitir, sin `Idempotency-Key` y sin consumir cupo: responde 200 con `{"valido":true,"errores":[]}` si el comprobante cumple todas las reglas, o el error que daría la emisión, por ejemplo 422 con el `codEstado` 3002 (`comprobante_invalido`). Es opcional; conviene para revisar lo que generes automáticamente antes de pedir confirmación. 5. El cuerpo lleva `origenReferencia`, `referenciaExterna`, `infoTributaria` (con `ruc`, `estab`, `ptoEmi` y `secuencial` opcional), `info` y la colección del tipo: `detalles`, `motivos`, `destinatarios` o `docsSustento`. No incluyas `tipoDocumento`: el tipo va en la ruta. 6. No envíes `claveAcceso`, `ambiente`, `tipoEmision`, `version` ni `formato`, porque son campos desconocidos y responden 422. Si omites `secuencial` o envías `"000000000"`, asignamos el siguiente. 7. La cabecera `Idempotency-Key` es obligatoria, en ASCII y con un máximo de 128 caracteres; si falta, la API responde 400 con el `codEstado` 3003 (`solicitud_invalida`). La misma clave con el mismo cuerpo devuelve el mismo `idOperacion` y el estado actual de la operación, y la misma clave con otro cuerpo responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). La clave se recuerda 7 días por integración y ambiente. 8. La emisión responde `202 Accepted` con un cuerpo plano que trae `estado` (normalmente `recibido`; `autorizado` si la autorización ya se conoce), `codEstado` (1001; 1002 si ya trae `claveAcceso`; 2001 si ya está autorizado; en los tres casos la respuesta es 202), `errores` (`[]` salvo un resultado final con detalle), `idOperacion`, `urlEstado` (la URL absoluta del seguimiento, igual a la cabecera `Location`), `ambiente`, `tipoDocumento`, `numeroDocumento`, `referenciaExterna`, `claveAcceso` (puede ser `null`), `fhRecibido` y `fhAutorizacion`, junto con la cabecera `X-Correlation-Id`. Un 202 no es una autorización salvo con `autorizado` (2001); un rechazo definitivo ya conocido responde `422` con el mismo cuerpo. La cabecera opcional `X-Additional-Info`, en ASCII imprimible y con un máximo de 256 caracteres, se asocia a tu solicitud para soporte y no cambia la respuesta. 9. El seguimiento es `GET /v1/operaciones/{idOperacion}` y devuelve la misma forma que el 202; se consulta mientras `estado` sea `recibido` (`codEstado` 1001 o 1002). Los estados finales son `autorizado` (2001), `rechazado` (3xxx), `rechazo_configuracion` (4xxx), `error` (5xxx) y `cancelado` (6001), y todos salvo `autorizado` traen `msgError` y el detalle en `errores`; en un rechazo del SRI (3001), `errores` trae su mensaje. El resultado también llega por los webhooks `document.authorized`, `document.rejected` y `document.failed`, que traen los mismos `estado`, `codEstado`, `msgError` y `errores`; `document.failed` indica que no se pudo emitir y no es un rechazo del SRI. 10. Los archivos se descargan con `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` (PDF) y `/xml`, usando la `claveAcceso` real de 49 dígitos que devuelve el seguimiento. 11. El error tiene un cuerpo plano `{"estado","codEstado","msgError","errores"}`, y el de la emisión tiene además los campos del 202 en `null`. `codEstado` es un número estable de 4 dígitos cuyo primer dígito es el `estado`; `errores` viene siempre, con detalle en los errores de validación y como `[]` en el resto. Decide por el estado HTTP y `codEstado`, no por `msgError`. El catálogo está en [Errores](/v1/guias/errores#catalogo-de-codestado). 12. Estos códigos se corrigen y no se reintentan: 3003 `solicitud_invalida` (HTTP 400, cabeceras o JSON), 3002 `comprobante_invalido` (HTTP 422, campos o regla fiscal; consume 1 documento como intento), 3006 `cuerpo_excedido` (HTTP 413), 3009 `credenciales_invalidas` (HTTP 401, API Key ausente o inválida), 3010 `ip_no_autorizada` (HTTP 403, IP no permitida), 3011 `acceso_denegado` (HTTP 403, permiso), 3004 `comprobante_duplicado` (HTTP 409) y 3005 `conflicto_idempotencia` (HTTP 409, misma clave con otro cuerpo). 13. Estos códigos se reintentan con espera y la misma `Idempotency-Key`: 5005 `limite_solicitudes` (HTTP 429; respeta `Retry-After`), 5001 `error_interno` (HTTP 500), 5002 `servicio_no_disponible`, 5003 `error_dependencia` y 5004 `tiempo_agotado` (HTTP 503, 502 y 504), y también los cortes de red. 4004 `cupo_agotado` (HTTP 429) indica que no queda cupo y no se resuelve reintentando. 14. Los límites son 200 solicitudes por minuto por integración (60 en un sandbox), 20 autenticaciones fallidas por minuto por IP, una profundidad JSON de 32 y un cuerpo de 1 MiB fuera de la emisión. Cada comprobante autorizado o rechazado consume un documento de tu cupo, y uno `cancelado` no lo consume. Sin API Key puedes consultar `GET /estado` (estado del servicio, hasta 60 consultas por minuto por IP) y con ella `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}` (catálogos del SRI). 15. Cada webhook lleva la firma `Ecuafact-Signature: t=,v1=`, calculada sobre `t + "." + cuerpo_crudo` con los bytes UTF-8 del secreto como clave, y además las cabeceras de Standard Webhooks (`webhook-id`, `webhook-timestamp` y `webhook-signature`), que verifican las librerías oficiales del estándar con el secreto, con o sin el prefijo `whsec_`. Basta con verificar una de las dos. Los duplicados se descartan por `eventType` + `resourceId`, o por `webhook-id`. El detalle de cada punto está en [Primeros pasos](/v1/guias/primeros-pasos), [Comprobantes electrónicos](/v1/guias/emision), [Errores](/v1/guias/errores), [Límites](/v1/guias/limites) y [Webhooks](/v1/guias/webhooks). ## Documentación para agentes La documentación se publica también en formatos pensados para que un agente la lea y la cite. | Recurso | Qué contiene | Uso recomendado | |---|---|---| | [llms.txt](/llms.txt) | Resumen esencial del contrato e índice con el enlace `.md` de cada guía, su descripción y su fecha de actualización. | Punto de entrada para decidir qué guía leer. | | [llms-full.txt](/llms-full.txt) | El mismo resumen y todas las guías completas en un archivo, en el orden del menú. | Cargar el contexto completo de una vez. | | `/v1/guias/{slug}.md` | Markdown de una guía (por ejemplo, `/v1/guias/emision-01.md`). También responde a `Accept: text/markdown` en la URL de la guía. | Leer el detalle vigente de un tema. | | [OpenAPI](/api/openapi.json) | Contrato de la API en formato máquina. | Generar clientes o validar campos. | | [Catálogo de servicios](/.well-known/api-catalog) | Enlaces a OpenAPI, documentación y versiones (RFC 9727). | Descubrimiento automático. | | [Versiones del contrato](/.well-known/api-versions.json) | Versión vigente, fechas y retiro. | Saber si una versión sigue vigente. | | [sitemap.xml](/sitemap.xml) | URLs de todas las guías. | Rastreo. | | [Versionado](/v1/guias/versionado) | Política de versiones y cabecera `X-Api-Version`. | Fijar una versión del contrato. | Cuando necesites un dato exacto, vuelve a leer la versión `.md` de la guía en lugar de confiar en una copia guardada, porque la guía en línea es la vigente. ## Metadatos citables Cada guía expone dos campos para que puedas citarla: | Campo | Contenido | |---|---| | `source_url` | URL canónica de la guía: `https://docs.mynexusapi.com/v1/guias/{slug}`. | | `last_updated` | Fecha (`aaaa-mm-dd`) del último cambio de la guía. | Los dos campos aparecen como un comentario al inicio de la versión `.md` de cada guía (``) y antes de cada guía en [llms-full.txt](/llms-full.txt). En [llms.txt](/llms.txt), cada entrada enlaza la versión `.md` y termina con `(actualizado: aaaa-mm-dd)`. Cita siempre `source_url`, y agrega `last_updated` cuando la respuesta dependa de un detalle fiscal o de contrato. ## Acciones con MCP Con nuestro servidor MCP, un asistente puede consultar y emitir mediante herramientas. Cada ambiente tiene su endpoint: | Ambiente | Endpoint (Streamable HTTP) | |---|---| | Pruebas | `https://mcp-sandbox.mynexusapi.com/mcp` | | Producción | `https://mcp.mynexusapi.com/mcp` | El acceso al servidor MCP es con OAuth 2.1 (`Authorization: Bearer`) y no con la API Key. Un asistente se conecta con la URL del endpoint y la persona aprueba sus permisos y sus RUC en el portal del cliente; un sistema sin persona usa un bot con `client_credentials`. El agente solo ve las herramientas y los RUC que se le concedieron. | Tipo | Herramientas | |---|---| | Lectura | `obtener_contexto`, `obtener_consumo`, `listar_operaciones`, `consultar_operacion`, `descargar_archivo`, `validar_identificacion`, `consultar_contribuyente`, `buscar_contribuyentes`, `listar_establecimientos`, `decodificar_clave_acceso`, `listar_catalogos`, `obtener_catalogo` y `obtener_estado_servicio`. | | Escritura | `validar_comprobante`, que valida sin emitir y es opcional, y `emitir_comprobante`, que exige `confirmar=true` e `idempotencyKey`. | | Perfil y webhooks | Con los permisos que concedas en la pantalla de consentimiento: `obtener_perfil`, `actualizar_perfil`, `actualizar_logo_perfil` y las herramientas de destinos y entregas de webhooks. Las que cambian algo exigen `confirmar=true`. | En `validar_comprobante` y `emitir_comprobante`, el parámetro `tipo` (`factura`, `liquidacion`, `nota-credito`, `nota-debito`, `guia` o `retencion`) elige la ruta del tipo, y la `estructura` es el cuerpo exacto de ese tipo, sin ningún campo de tipo: si trae `infoTributaria.tipoDocumento`, la API responde el error de validación 3002 (`comprobante_invalido`) con el campo en `errores`. La configuración de cada cliente, los permisos y los parámetros de cada herramienta están en [MCP y asistentes](/v1/guias/mcp). ## Skill Puedes cargar en el asistente el conocimiento de la API con nuestro skill, un paquete descargable, [`ecuafact.zip`](/downloads/v1/skills/ecuafact.zip), con `SKILL.md` y la carpeta `reference/`. Su instalación se explica en [Skill para asistentes de IA](/v1/guias/skill). ## CLI Con nuestro [CLI](/v1/guias/cli) instalado, el agente puede consultar, emitir y descargar comprobantes desde la terminal. `ecuafact schema` describe todos los comandos en JSON, y cuando el CLI no se ejecuta en una terminal, también responde en JSON. La API Key va en `ECUAFACT_API_KEY` y nunca como argumento. Agrega `--confirmar produccion` solo cuando el usuario lo pidió para ese envío. Los códigos de salida para interpretar el resultado están en la [Referencia de comandos](/v1/guias/cli-referencia#codigos-de-salida). ## Reglas para agentes 1. **No inventes contrato.** Endpoints, campos, códigos y límites salen de esta documentación. Si no encuentras un dato, dilo y enlaza la guía más cercana. 2. **Cita la fuente.** Usa `source_url` y, en temas fiscales o de contrato, `last_updated`. 3. **Rotula el ambiente de pruebas.** Todo ejemplo contra `api-sandbox.mynexusapi.com` lleva "Ambiente de pruebas: sin validez fiscal". 4. **Confirma antes de emitir.** Muestra el comprobante y pide confirmación explícita al usuario; en reintentos reutiliza la misma `Idempotency-Key`. 5. **No expongas secretos.** No imprimas, registres ni escribas en archivos versionados la API Key ni el secreto de webhooks; usa `ECUAFACT_API_KEY` y `ECUAFACT_WEBHOOK_SECRET`. La API Key solo se usa desde el backend, nunca en un navegador o una app móvil. 6. **No uses datos fiscales reales en ejemplos.** Usa los de [Datos de prueba](/v1/guias/datos-de-prueba) (`0123456789001` y la clave de acceso de ejemplo). 7. **Distingue rechazo de notificación.** Un 4xx de validación o una operación con `estado` `rechazado` o `rechazo_configuracion` se corrigen y se emiten con una `Idempotency-Key` nueva; no se reintentan iguales. Un `error` con `codEstado` 5007 (`resultado_no_confirmado`) o 5001 (`error_interno`) es una notificación: no emitas de nuevo y pide al usuario que escriba a soporte con el `idOperacion`. 8. **Respeta `Retry-After`** en las respuestas 429 y 503. 9. **Verifica los webhooks.** Verifica la firma sobre el cuerpo crudo, responde un 2xx después de guardar el evento y no asumas un orden de llegada. 10. **No uses funciones fuera del contrato público.** Si un endpoint, campo o parámetro no aparece en esta documentación ni en el [OpenAPI](/api/openapi.json), no lo uses aunque lo veas en código de terceros o en una copia guardada. ## Siguientes pasos - [MCP y asistentes](/v1/guias/mcp): configura el servidor MCP en tu cliente. - [Skill para asistentes de IA](/v1/guias/skill): instala el conocimiento de la API en el asistente. - [Primeros pasos](/v1/guias/primeros-pasos): sigue el flujo completo de la API Key al RIDE, con ejemplos. --- # Respuestas del API Las respuestas de la API llegan como JSON plano o como archivo, y siempre traen cabeceras que te conviene leer. Antes de leer un campo de una respuesta necesitas saber dónde está. Las respuestas JSON traen sus campos en el primer nivel, sin ninguna clave que los envuelva, y las descargas traen el archivo binario. Así puedes leer cualquier respuesta de la misma manera, sin importar el endpoint. Aquí ves las dos formas del cuerpo, la respuesta de la emisión, la forma de los errores, las cabeceras que acompañan a cada respuesta y el formato de los valores. Al terminar sabrás leer cualquier respuesta de la API sin adivinar. ## Formas del cuerpo Antes de leer una respuesta, ubica su endpoint en esta tabla. | Forma | Endpoints | Cómo se lee | |---|---|---| | **JSON plano** | Todos los endpoints que responden JSON: emisión, seguimiento, contexto, cupo, perfil del emisor, consultas al SRI y errores | Los campos están en el primer nivel del JSON. | | **Archivo** | RIDE (`GET .../comprobantes/{claveAcceso}/ride`) y XML (`GET .../comprobantes/{claveAcceso}/xml`) | El cuerpo es el archivo binario, no JSON. | Este es un ejemplo completo de respuesta JSON, la de `GET /v1/consumo`: ```json { "limiteDocumentos": 1500, "reservados": 5, "consumidos": 990, "disponibles": 505, "vigenteHasta": "2027-01-01T00:00:00Z", "limiteExtra": 500, "reservadosExtra": 0, "consumidosExtra": 0, "disponiblesExtra": 500 } ``` | Campo | Tipo | Descripción | |---|---|---| | Campos del recurso | varios | Están en el primer nivel. El detalle está en [Consumo y cuotas](/v1/guias/consumo). | ### Lee una respuesta en tu código El ejemplo consulta tu cupo y el seguimiento de una operación, e imprime un campo de cada una. Reemplaza el `idOperacion` por uno que te haya devuelto una emisión. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/consumo" \ -H "X-Api-Key: $ECUAFACT_API_KEY" curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; using System.Text.Json; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage consumo = await http.GetAsync("/v1/consumo"); using JsonDocument cupo = JsonDocument.Parse(await consumo.Content.ReadAsStringAsync()); Console.WriteLine($"{(int)consumo.StatusCode} disponibles: {cupo.RootElement.GetProperty("disponibles").GetInt32()}"); using HttpResponseMessage operacion = await http.GetAsync("/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"); using JsonDocument seguimiento = JsonDocument.Parse(await operacion.Content.ReadAsStringAsync()); Console.WriteLine($"{(int)operacion.StatusCode} estado: {seguimiento.RootElement.GetProperty("estado").GetString()}"); ``` ```python import os import requests base = "https://api-sandbox.mynexusapi.com" headers = {"X-Api-Key": os.environ["ECUAFACT_API_KEY"]} consumo = requests.get(f"{base}/v1/consumo", headers=headers, timeout=30) print(consumo.status_code, "disponibles:", consumo.json()["disponibles"]) operacion = requests.get(f"{base}/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", headers=headers, timeout=30) print(operacion.status_code, "estado:", operacion.json()["estado"]) ``` ```javascript // Node.js 18 o superior. Guarda como respuestas.mjs y ejecuta: node respuestas.mjs const base = 'https://api-sandbox.mynexusapi.com'; const headers = { 'X-Api-Key': process.env.ECUAFACT_API_KEY }; const consumo = await fetch(`${base}/v1/consumo`, { headers }); const cupo = await consumo.json(); console.log(consumo.status, 'disponibles:', cupo.disponibles); const operacion = await fetch(`${base}/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f`, { headers }); const seguimiento = await operacion.json(); console.log(operacion.status, 'estado:', seguimiento.estado); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); return [$estado, json_decode($cuerpo, true)]; } [$estado, $cupo] = consultar('/v1/consumo'); echo $estado . ' disponibles: ' . $cupo['disponibles'] . PHP_EOL; [$estado, $seguimiento] = consultar('/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f'); echo $estado . ' estado: ' . $seguimiento['estado'] . PHP_EOL; ``` ```bash-cli # Resultado esperado: tus documentos disponibles y el estado de la operación. ecuafact consumo --entorno sandbox --campos disponibles ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox --campos estado ``` **Resultado esperado.** Los ejemplos HTTP imprimen `200 disponibles: ...` y `200 estado: ...`. Si la operación no existe en tu integración, la segunda llamada responde 404 con el `codEstado` 3013 (`no_encontrado`), como se explica en [Respuestas de error](#respuestas-de-error). ## Respuesta de la emisión La emisión responde `202 Accepted` con este cuerpo, que tiene la misma forma del [seguimiento](/v1/guias/consulta-operacion): ```json { "estado": "recibido", "codEstado": 1001, "errores": [], "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": "001-001-000000123", "referenciaExterna": "FAC-ERP-4581", "claveAcceso": null, "fhRecibido": "2026-11-09T10:15:00-05:00", "fhAutorizacion": null } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | `recibido` en el 202: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. | | `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu sistema debe aceptar los dos valores. | | `errores` | array de string | Lista vacía cuando el comprobante se recibió sin novedades. | | `idOperacion` | string (UUID) | Identificador de la [operación](/v1/guias/glosario#operacion). Guárdalo, porque con él consultas el resultado del SRI. | | `urlEstado` | string | URL completa del seguimiento, por ejemplo `https://api-sandbox.mynexusapi.com/v1/operaciones/{idOperacion}`. Puedes llamarla tal como viene. | | `ambiente` | number | `1` para pruebas y `2` para producción. | | `tipoDocumento` | string | Tipo de comprobante: `01`, `03`, `04`, `05`, `06` o `07`. | | `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. | | `referenciaExterna` | string o `null` | La `referenciaExterna` que enviaste. | | `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes después en el seguimiento o en el webhook. | | `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. | | `fhAutorizacion` | string o `null` | Fecha y hora de autorización; en el 202 es `null`. | El campo `msgError` no aparece porque la emisión no tiene error. Si reintentas con la misma `Idempotency-Key` y el mismo cuerpo, o con la misma `referenciaExterna` y el mismo cuerpo, la API responde con la misma forma y el mismo `idOperacion`, con el estado actual de esa operación, y no crea otro comprobante. El resultado actual también lo ves en el [seguimiento](/v1/guias/consulta-operacion). > [!NOTE] > El 202 significa que la solicitud fue recibida; la autorización del SRI llega > después por [seguimiento](/v1/guias/consulta-operacion) o por > [webhook](/v1/guias/webhooks). ## Respuestas de error Todos los errores tienen la misma forma plana, con un `codEstado` numérico de 4 dígitos cuyo primer dígito coincide con el `estado`: ```json { "estado": "rechazado", "codEstado": 3013, "msgError": "Recurso no encontrado.", "errores": [] } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | Estado que corresponde al código: `rechazado` (3xxx), `rechazo_configuracion` (4xxx) o `error` (5xxx). | | `codEstado` | number | Código estable del catálogo. Programa tus decisiones con este valor y el estado HTTP. | | `msgError` | string | Descripción general y fija del código. | | `errores` | array de string | Detalle específico, por ejemplo la ruta del campo en un error de validación. Viene siempre y es una lista vacía cuando no hay detalle. | Un rechazo de la emisión, por ejemplo un 422 de validación, trae estos mismos cuatro campos dentro de la forma completa de la respuesta de emisión, con `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`, porque no se creó ninguna operación. Qué significa cada código y si se reintenta se explica en [Errores](/v1/guias/errores#catalogo-de-codestado). ## Cabeceras de respuesta Además del cuerpo, cada respuesta trae cabeceras con información útil para tu integración: | Cabecera | Cuándo aparece | Qué contiene | Para qué te sirve | |---|---|---|---| | `X-Correlation-Id` | En toda respuesta. | El identificador de la petición. Si enviaste tu propio `X-Correlation-Id` (de 1 a 64 caracteres `A-Z`, `a-z`, `0-9`, `.`, `_`, `-`), la API usa y devuelve ese mismo valor. | Regístralo en tus logs, porque es el dato que te pedimos en soporte. | | `X-Api-Version` | En toda respuesta de `/v1`. | La versión del contrato que respondió (`2026-11-16`). | Te permite detectar cambios de versión, como se explica en [Versionado](/v1/guias/versionado). | | `Location` | En el 202 de la emisión. | La URL completa del seguimiento, el mismo valor que `urlEstado`. | Úsala para consultar el estado. | | `Content-Type` | En toda respuesta con cuerpo. | `application/json` en JSON, `application/pdf` en el RIDE y `application/xml` en el XML. | Te dice cómo leer el cuerpo. | | `Content-Disposition` | En la descarga del XML. | `attachment` con el nombre de archivo sugerido `{claveAcceso}.xml`. | Úsala para guardar el archivo con su nombre. | | `X-RateLimit-Limit` | En las respuestas autenticadas, cuando tu API Key tiene límite. | Las solicitudes permitidas por minuto. | Te dice tu límite; más detalle en [Límite de request](/v1/guias/limite-de-request). | | `X-RateLimit-Remaining` | Junto con `X-RateLimit-Limit`. | Las solicitudes que te quedan en el minuto. | Te permite frenar antes de recibir un 429. | | `X-RateLimit-Reset` | En el 429 con el `codEstado` 5005 (`limite_solicitudes`). | El fin de la ventana, en segundos Unix. | Te dice cuándo vuelves a tener solicitudes. | | `Retry-After` | En los 429 y 503. | Los segundos de espera antes de reintentar. | Úsala para programar el reintento. | | `Cache-Control` | En toda respuesta de `/v1`. | `no-store`, salvo en `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}`, que traen `private, max-age=3600`. | Con `no-store`, las respuestas no se guardan en cachés intermedias; tampoco las guardes tú sin control. Los catálogos sí puedes guardarlos hasta una hora, como se explica en [Consultar los catálogos por API](/v1/guias/catalogos#consultar-los-catalogos-por-api). | Así se ven las cabeceras de una emisión: ``` HTTP/1.1 202 Accepted Content-Type: application/json; charset=utf-8 Location: https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f X-Correlation-Id: 0HN7A2B3C4D5E:00000001 X-Api-Version: 2026-11-16 X-RateLimit-Limit: 200 X-RateLimit-Remaining: 199 Cache-Control: no-store ``` ## Formatos de los valores Los valores de las respuestas siguen estos formatos: | Tipo de dato | Formato | Ejemplo | |---|---|---| | Identificadores (`idOperacion`, `idCliente`) | UUID en texto. | `"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"` | | Códigos e identificaciones (`tipoDocumento`, `identificacion`, `claveAcceso`) | Texto, aunque solo tengan dígitos, para conservar los ceros a la izquierda. | `"01"`, `"0123456789"` | | Códigos de resultado y de error (`codEstado`) | Número entero de 4 dígitos. El primer dígito coincide con el `estado`. | `3002` | | Estados (`estado`) | Texto en minúsculas con guion bajo. | `"recibido"`, `"rechazo_configuracion"` | | Importes | Número JSON con punto decimal. | `112.5` | | Fechas del comprobante (`fechaEmision` del listado de operaciones) | Texto con el formato `dd/MM/yyyy`. | `"15/09/2026"` | | Fechas y horas de las respuestas (`fhRecibido`, `fhAutorizacion`, `vigenteHasta`) | Texto ISO 8601 (`yyyy-MM-ddTHH:mm:ss`). Algunos campos agregan la zona horaria al final (`Z` o `-05:00`), así que usa un parser ISO 8601 que acepte las dos formas. | `"2026-09-15T14:32:10"` | | Campos opcionales sin valor | `null`. La excepción es `msgError`, que no aparece cuando no hay error. | `"fhAutorizacion": null` | ## Siguientes pasos - [Errores](/v1/guias/errores#catalogo-de-codestado): qué hacer ante cada `codEstado`. - [Seguimiento de una operación](/v1/guias/consulta-operacion): los campos del estado de una emisión. - [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar. - [Versionado](/v1/guias/versionado): cómo cambia el contrato y qué significa `X-Api-Version`. - [Estado del servicio](/v1/guias/estado-del-servicio): consulta sin API Key si la API está operativa cuando recibes errores 5xx. --- # Errores Cada respuesta de la API trae un `codEstado` numérico que te dice qué pasó y si debes esperar, reintentar o corregir; aquí está el catálogo completo. Cuando una petición falla, la API responde con un estado HTTP y un cuerpo JSON que trae el `estado`, un `codEstado` de cuatro dígitos, como 3002 o 4004, un `msgError` con la descripción general del código y la lista `errores` con el detalle. El `codEstado` es estable, así que puedes programar tus decisiones con él: reintentar después de esperar, corregir el comprobante o avisar a una persona. El mismo número aparece en el seguimiento de una operación y en los webhooks, de modo que un solo catálogo te sirve para todo. Aquí encuentras la forma del error, cómo leer un código por su primer dígito, el catálogo completo de `codEstado` con qué hacer ante cada uno, los códigos de resultado de una operación que no terminó autorizada, los errores que puede devolver cada tipo de petición y un ejemplo de cómo manejarlos en tu código. Al final encontrarás qué datos incluir cuando pidas soporte. ## Forma del error Todos los endpoints responden sus errores con un estado HTTP 4xx o 5xx y un JSON plano como este: ```json { "estado": "rechazado", "codEstado": 3003, "msgError": "La solicitud no es válida.", "errores": [ "Idempotency-Key: La cabecera Idempotency-Key es obligatoria y debe ser ASCII estable (maximo 128 caracteres)." ] } ``` | Campo | Tipo | Descripción | |---|---|---| | `estado` | string | Estado del resultado. Lo fija el primer dígito de `codEstado`: en un error HTTP es `rechazado`, `rechazo_configuracion` o `error`. | | `codEstado` | integer | Código estable del [catálogo](#catalogo-de-codestado), de cuatro dígitos. Programa tus decisiones con este número. | | `msgError` | string | Descripción general y fija del código, igual para todas las respuestas con ese `codEstado`. Puedes mostrarla a un operador, pero no la compares en tu código. Se omite cuando no hay error. | | `errores` | array de string | Detalle específico del caso. Viene siempre y es una lista vacía cuando no hay detalle. En 3002 (`comprobante_invalido`) trae hasta 20 elementos, uno por problema; cuando el problema es de un campo concreto, el texto suele empezar con su ruta, por ejemplo `$.infoTributaria.estab: Solo se admiten digitos.`, y algunas rutas aparecen con nombres en inglés, como `items.code`. En 3003 (`solicitud_invalida`) trae el detalle de los parámetros inválidos; puede ser más de uno. En un rechazo del SRI trae el mensaje del SRI. El texto es informativo y puede cambiar, así que muéstralo o regístralo, pero no lo compares en tu código. | Cada endpoint de emisión por tipo, por ejemplo `POST /v1/contribuyentes/{identificacion}/facturas`, responde sus rechazos con la misma forma que su respuesta 202 y que el [seguimiento de una operación](/v1/guias/consulta-operacion), para que puedas leer las tres con el mismo código. En un rechazo, `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso`, `fhRecibido` y `fhAutorizacion` llegan en `null`, mientras que `ambiente`, `tipoDocumento` y `referenciaExterna` traen su valor cuando la API pudo leerlo de tu solicitud: ```json { "estado": "rechazado", "codEstado": 3002, "msgError": "El comprobante no cumple las validaciones.", "errores": [ "$.infoTributaria.estab: Solo se admiten digitos." ], "idOperacion": null, "urlEstado": null, "ambiente": 1, "tipoDocumento": "01", "numeroDocumento": null, "referenciaExterna": "FAC-ERP-4581", "claveAcceso": null, "fhRecibido": null, "fhAutorizacion": null } ``` Toda respuesta, con error o sin él, trae la cabecera `X-Correlation-Id`, con la que podemos ubicar esa petición cuando nos escribes. Te recomendamos guardarla junto con el error, porque es lo primero que te pedimos en soporte. > [!NOTE] > Decide siempre con la pareja de estado HTTP y `codEstado`. Un mismo código > puede llegar con dos estados HTTP distintos según el endpoint. ## Cómo leer un error El `codEstado` tiene cuatro dígitos, y el primero te dice el `estado` sin necesidad de buscar el código en el catálogo. Así puedes escribir una regla general por familia y afinar solo los códigos que necesitan un trato especial. ### El estado y el primer dígito | Primer dígito | `estado` | Qué significa | Acción general | |---|---|---|---| | 1 | `recibido` | La API recibió el comprobante y todavía no hay un resultado final. | Espera el resultado en el seguimiento o en un webhook. | | 2 | `autorizado` | El SRI autorizó el comprobante; es el único resultado con validez fiscal. | Guarda la `claveAcceso` y entrega el comprobante. | | 3 | `rechazado` | La solicitud o el comprobante tienen un problema, o el SRI rechazó el comprobante. | Lee `errores`, corrige y vuelve a enviar. No reintentes la misma petición sin cambios. | | 4 | `rechazo_configuracion` | Falta configuración del emisor o de tu cuenta: firma o cupo. | Corrige la configuración en el Portal del Cliente y después vuelve a emitir. | | 5 | `error` | Tuvimos una falla nuestra o de un servicio del que dependemos, o superaste el límite de solicitudes. | Reintenta con espera; en una emisión, con la misma `Idempotency-Key`. Las excepciones están en el catálogo. | | 6 | `cancelado` | La plataforma canceló el envío antes de emitir el comprobante. | Emite de nuevo con claves nuevas. | Como regla práctica, un 4xx no se arregla reintentando la misma petición, salvo el 429 por límite de solicitudes después de esperar. Un 5xx o un corte de red, en cambio, sí se reintentan. ### Los dos 429 El estado HTTP 429 llega con dos códigos que piden acciones opuestas, así que siempre debes mirar el `codEstado` antes de decidir. Con 5005 (`limite_solicitudes`) superaste las solicitudes por minuto: espera los segundos que indica la cabecera `Retry-After` y repite la misma petición. Con 4004 (`cupo_agotado`) no te quedan documentos en paquetes vigentes: esperar no lo repone, así que no reintentes y compra un paquete, como se explica en [Consumo](/v1/guias/consumo). ## Catálogo de `codEstado` Esta es la lista completa de códigos. El nombre de cada código no viaja en el JSON, donde solo llega el número, pero te sirve para leer la documentación y coincide con las constantes de nuestros SDK. La columna **HTTP** indica el estado HTTP con el que llega el código en una respuesta sincrónica; «seguimiento» significa que lo ves en el [seguimiento](/v1/guias/consulta-operacion) y en los [webhooks](/v1/guias/webhooks), no como un error HTTP. La columna **¿Reintentar?** indica si puedes repetir la misma petición sin cambiarla. «Con la misma Idempotency-Key» significa que, en una emisión, repites el mismo cuerpo con la misma cabecera `Idempotency-Key` para no duplicar el comprobante; en una consulta `GET`, basta con repetirla. Si recibes un código que no está en esta lista, trátalo según su primer dígito y avisa a una persona. ### Recibido y autorizado Estos códigos no son errores: no traen `msgError` y su `errores` llega vacío. | codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? | |---|---|---|---|---|---|---|---| | 1001 | `comprobante_recibido` | `recibido` | 202 / seguimiento | Se omite. | La API recibió la emisión y el comprobante todavía no tiene clave de acceso; `claveAcceso` llega en `null`. | Guarda el `idOperacion` y espera el resultado en el seguimiento o en un webhook. | No hace falta | | 1002 | `comprobante_enviado` | `recibido` | 202 / seguimiento | Se omite. | El comprobante ya tiene su clave de acceso, que llega en `claveAcceso`, y espera la respuesta del SRI. | Guarda la `claveAcceso` y sigue esperando el resultado final. | No hace falta | | 2001 | `comprobante_autorizado` | `autorizado` | Seguimiento | Se omite. | El SRI autorizó el comprobante. `fhAutorizacion` trae la fecha de autorización. | Guarda la `claveAcceso`, descarga el [RIDE](/v1/guias/consulta-ride) o el [XML](/v1/guias/consulta-xml) y entrega el comprobante. | No hace falta | La respuesta 202 de la emisión trae `estado` en `recibido` con 1001 o 1002, o `autorizado` con 2001 si la autorización ya se conoce. Acepta los tres códigos en tu integración, guarda la `claveAcceso` solo cuando no llegue en `null` y procesa el cuerpo del 202 con la misma lógica que usas para el seguimiento, porque las dos respuestas tienen la misma forma. Un rechazo definitivo que la emisión ya conoce responde `422`, no `202`. ### Rechazado | codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? | |---|---|---|---|---|---|---|---| | 3001 | `rechazo_sri` | `rechazado` | 422 / seguimiento | El SRI rechazó el comprobante. | El SRI rechazó el comprobante. `errores` trae el mensaje del SRI. El cupo se consume. Si la emisión directa ya conoce el rechazo, responde `422` con `idOperacion` y `urlEstado`; ese `422` consume cupo. | Corrige el comprobante según `errores` y emítelo como un comprobante nuevo, con un secuencial nuevo, u omitiéndolo, y claves nuevas. | No; emite uno nuevo | | 3002 | `comprobante_invalido` | `rechazado` | 422 / seguimiento | El comprobante no cumple las validaciones. | La Estructura del comprobante no cumple una regla: falta un campo obligatorio, un formato es incorrecto, los totales o impuestos no cuadran, hay campos de otro tipo dentro de `info`, hay campos desconocidos o repetidos, `infoTributaria.ruc` es distinto de la identificación de la ruta, o enviaste `version`, `formato`, `ambiente`, `tipoEmision` o `infoTributaria.tipoDocumento`, que no se admite porque la ruta fija el tipo. En XML también ocurre si la raíz o `infoTributaria.codDoc` no corresponden a la ruta, o si la retención usa el XML 1.0 sin `docsSustento`. En el seguimiento, la validación fiscal rechazó el contenido antes de enviarlo al SRI. | Lee `errores`, que trae la ruta del campo, corrige el comprobante y vuelve a enviarlo. Un 422 de validación consume 1 documento como intento; repetir la misma `Idempotency-Key` con el mismo cuerpo no consume otro. | No | | 3003 | `solicitud_invalida` | `rechazado` | 400, 405, 415 | La solicitud no es válida. | El cuerpo no es JSON ni XML válido; falta `Idempotency-Key` o tiene caracteres no permitidos o más de 128; un parámetro de ruta o de consulta tiene un tipo inválido; usaste un método HTTP que la ruta no admite; el `Content-Type` no es `application/json`, `application/xml` ni `text/xml`; o, al crear un destino de webhooks en pruebas, ya tienes 10 sin deshabilitar. | Lee `errores`, corrige y vuelve a enviar. | No | | 3004 | `comprobante_duplicado` | `rechazado` | 409 | Ya existe un comprobante con ese número. | Ya existe un comprobante con el mismo contribuyente, tipo, establecimiento, punto de emisión y secuencial, y está `recibido`, `autorizado` o `rechazado` por el SRI. El número solo se puede reutilizar cuando la operación anterior no llegó a emitir el comprobante, como se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion#que-hacer-segun-el-estado). | No lo reenvíes. Busca el comprobante existente en el seguimiento. Si querías otro comprobante, usa otro secuencial u omítelo para que se asigne el siguiente. | No | | 3005 | `conflicto_idempotencia` | `rechazado` | 409 | La Idempotency-Key ya se usó con otro contenido. | Reutilizaste una `Idempotency-Key`, o una `referenciaExterna` con el mismo `origenReferencia`, con un cuerpo distinto al original; o la `referenciaExterna` ya pertenece a otro comprobante del mismo contribuyente. | Si es un reintento, reenvía exactamente el cuerpo original. Si es otra emisión, usa una `Idempotency-Key` y una `referenciaExterna` nuevas, como se explica en [Buenas prácticas](/v1/guias/buenas-practicas#idempotencia). | No | | 3006 | `cuerpo_excedido` | `rechazado` | 413 | El cuerpo supera el tamaño permitido. | El cuerpo supera 2 MiB en la emisión o 1 MiB en otros `POST` y `PUT`. | Reduce el tamaño del cuerpo, como se explica en [Límites](/v1/guias/limites). | No | | 3007 | `version_no_soportada` | `rechazado` | 400 | Versión de API no admitida. | Enviaste `X-Api-Version` con un valor no admitido. | Envía `2026-11-16` o no envíes la cabecera; el detalle está en [Versionado](/v1/guias/versionado). | No | | 3008 | `no_implementado` | `rechazado` | 501 | Formato no admitido. | Reservado. La API no devuelve este código actualmente. | Si lo recibes, envía el comprobante en JSON o en el XML del SRI y escribe a [soporte](#como-pedir-soporte) con el `X-Correlation-Id`. | No | | 3009 | `credenciales_invalidas` | `rechazado` | 401 | Credenciales inválidas. | Falta `X-Api-Key`, la API Key está mal formada, no existe, está revocada, venció o pertenece a otro ambiente. | Revisa la cabecera y la API Key, como se explica en [Autenticación](/v1/guias/autenticacion#cuando-aparece-3009). | No | | 3010 | `ip_no_autorizada` | `rechazado` | 403 | IP no autorizada. | En producción, la API Key es válida, pero la IP de origen no está registrada para tu integración, o la API no pudo identificar la IP de la conexión. El sandbox no exige IP registrada. | Registra tu IP pública de producción en **Cuenta > IP permitidas** o llama directo a la URL de la API, como se explica en [Autenticación](/v1/guias/autenticacion#cuando-aparece-3010). | No | | 3011 | `acceso_denegado` | `rechazado` | 403 | Contribuyente, tipo o suscripción no habilitados. | El contribuyente de la ruta o el tipo de comprobante no están habilitados para tu integración. | Revisa `GET /v1/contexto`, como se explica en [Ambientes](/v1/guias/ambientes). | No | | 3012 | `filtros_invalidos` | `rechazado` | 400 | Filtros inválidos. | Un filtro de una consulta está fuera de rango: fechas o `max`. | Ajusta los filtros a los [límites](/v1/guias/limites). | No | | 3013 | `no_encontrado` | `rechazado` | 404 | Recurso no encontrado. | El `idOperacion`, la clave de acceso o el RIDE no existen, no pertenecen a tu integración o aún no están disponibles; o tu integración no tiene paquetes en este ambiente (`GET /v1/consumo`). Un contribuyente de marca blanca, con `marcaBlanca` en `true` en [`/v1/contexto`](/v1/guias/consulta-contexto), no tiene RIDE y recibe siempre este código al pedirlo. | Revisa el identificador y la URL del ambiente. Si es un RIDE recién autorizado, reintenta más tarde. Si el contribuyente es de marca blanca, descarga el [XML](/v1/guias/consulta-xml). | No; un RIDE recién autorizado, sí, más tarde, salvo en marca blanca | | 3014 | `correo_no_disponible` | `rechazado` | 409 | Correo no disponible para el emisor. | Reservado. El reenvío de correo no está disponible. | Descarga el [XML](/v1/guias/consulta-xml) y envía el comprobante desde tu sistema. | No | ### Rechazo de configuración | codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? | |---|---|---|---|---|---|---|---| | 4001 | `emisor_no_configurado` | `rechazo_configuracion` | 422 / seguimiento | Al emisor le falta configuración. | Al emisor le falta configuración para emitir ante el SRI. | Revisa el RUC en **Cuenta > Contribuyentes** del Portal del Cliente: en el ambiente en que emitiste, la columna **Pruebas** o **Producción** debe mostrar **Listo** o **En producción**. Si muestra **Configurando**, espera a que termine; si ya está listo, escribe a soporte con el `idOperacion`. Después reenvía con claves nuevas. | No; reenvía después de corregir | | 4002 | `firma_no_valida` | `rechazo_configuracion` | 422 / seguimiento | La firma electrónica no es válida. | La firma electrónica del emisor está caducada o no es válida. | En **Cuenta > Contribuyentes** del Portal del Cliente, pulsa **Reemplazar firma** en la fila del RUC y carga una firma electrónica vigente; si tu portal no muestra esa opción, cárgala en **Cuenta > Certificados** con **Reemplazar certificado**. Después reenvía con claves nuevas. | No; reenvía después de corregir | | 4003 | `suscripcion_inactiva` | `rechazo_configuracion` | 422 / seguimiento | La suscripción no está activa. | El servicio de emisión de tu cuenta no está activo en este ambiente. | Escribe a [soporte](#como-pedir-soporte) para reactivarlo y reenvía con claves nuevas. | No; reenvía después de corregir | | 4004 | `cupo_agotado` | `rechazo_configuracion` | 429 / seguimiento | Cupo agotado. | No te quedan documentos en tus paquetes vigentes. | Consulta [`GET /v1/consumo`](/v1/guias/consumo) y compra un paquete. Esperar lo que indica `Retry-After` no lo repone. | No, hasta ampliar el cupo | ### Error | codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? | |---|---|---|---|---|---|---|---| | 5001 | `error_interno` | `error` | 500 / seguimiento | Error interno. | Tuvimos un fallo no previsto. En el seguimiento, el comprobante no se completó. | En una respuesta 500, reintenta con espera exponencial y, si persiste, reporta el `X-Correlation-Id` a [soporte](#como-pedir-soporte). En el seguimiento, escribe a soporte con el `idOperacion` antes de reemitir. | 500: con la misma Idempotency-Key. Seguimiento: no, hasta que soporte lo confirme | | 5002 | `servicio_no_disponible` | `error` | 503 | Servicio temporalmente no disponible. | Nuestro servicio no está disponible por un momento. | Espera los segundos que indica `Retry-After` y reintenta. | Con la misma Idempotency-Key | | 5003 | `error_dependencia` | `error` | 502 | Un servicio externo reportó un error. | Un servicio externo devolvió un error en una llamada sincrónica: [consultas al SRI](/v1/guias/consulta-contribuyente), el seguimiento, descarga del [RIDE](/v1/guias/consulta-ride) o del [XML](/v1/guias/consulta-xml), o [perfil del emisor](/v1/guias/perfil-emisor). | Reintenta con espera. Si persiste, reporta el `X-Correlation-Id`. | Sí | | 5004 | `tiempo_agotado` | `error` | 504 | Un servicio externo no respondió a tiempo. | Un servicio externo no respondió a tiempo en una consulta sincrónica: [consultas al SRI](/v1/guias/consulta-contribuyente), el seguimiento, descarga del RIDE o del XML, o [perfil del emisor](/v1/guias/perfil-emisor). | Reintenta con espera. | Sí | | 5005 | `limite_solicitudes` | `error` | 429 | Límite de solicitudes excedido. | Superaste las solicitudes por minuto de tu integración, tu IP acumuló 20 autenticaciones fallidas en el minuto, o el servicio externo de una consulta al SRI limitó las solicitudes. | Espera los segundos que indica `Retry-After`; el detalle está en [Límite de request](/v1/guias/limite-de-request). | Con la misma Idempotency-Key, después de `Retry-After` | | 5006 | `entrega_no_posible` | `error` | Seguimiento | El comprobante no se pudo emitir. | El comprobante no se pudo emitir y confirmamos que no se creó. | Reenvía con claves nuevas. | Sí, con claves nuevas | | 5007 | `resultado_no_confirmado` | `error` | Seguimiento | No se pudo confirmar el resultado. | No pudimos confirmar si el comprobante llegó a crearse. | No reemitas, porque podrías duplicarlo. Búscalo en el seguimiento y escribe a [soporte](#como-pedir-soporte) con el `idOperacion`. | No, hasta que soporte lo confirme | ### Cancelado | codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? | |---|---|---|---|---|---|---|---| | 6001 | `operacion_cancelada` | `cancelado` | Seguimiento | La plataforma canceló el envío. | La plataforma canceló el envío antes de emitir el comprobante. No consumió cupo y no genera webhook. | Emite de nuevo con claves nuevas. | Sí, con claves nuevas | ## Códigos de resultado de una operación Una emisión que respondió 202 no termina con un error HTTP, aunque no llegue a autorizarse. El resultado lo ves en el `estado` del [seguimiento](/v1/guias/consulta-operacion) y en el cuerpo de los [webhooks](/v1/guias/webhooks). Cuando ese `estado` es final y distinto de `autorizado`, el campo `codEstado` trae uno de estos códigos, `msgError` su descripción general y `errores` el detalle del caso, por ejemplo el mensaje del SRI en un 3001. En la tabla, «claves nuevas» significa una `Idempotency-Key` nueva y una `referenciaExterna` nueva, y «el mismo número» significa el mismo `estab`, `ptoEmi` y `secuencial` del comprobante anterior. | codEstado | Nombre | Estado | Qué hacer | Reenviar | |---|---|---|---|---| | 3001 | `rechazo_sri` | `rechazado` | Corrige el comprobante según el mensaje del SRI que trae `errores` y emítelo como un comprobante nuevo, con un secuencial nuevo, u omitiéndolo, y claves nuevas. | Sí, con otro número | | 3002 | `comprobante_invalido` | `rechazado` | Corrige el dato que indica `errores` y reenvía con claves nuevas. | Sí, con el mismo número | | 4001 | `emisor_no_configurado` | `rechazo_configuracion` | Completa la configuración del emisor en el Portal del Cliente y reenvía con claves nuevas. | Sí, con el mismo número | | 4002 | `firma_no_valida` | `rechazo_configuracion` | Carga una firma electrónica vigente y reenvía con claves nuevas. | Sí, con el mismo número | | 4003 | `suscripcion_inactiva` | `rechazo_configuracion` | Escribe a [soporte](#como-pedir-soporte) para reactivar el servicio de emisión y reenvía con claves nuevas. | Sí, con el mismo número | | 4004 | `cupo_agotado` | `rechazo_configuracion` | Compra un paquete de documentos y reenvía con claves nuevas. | Sí, con el mismo número | | 5006 | `entrega_no_posible` | `error` | Reenvía con claves nuevas. | Sí, con el mismo número | | 5007 | `resultado_no_confirmado` | `error` | No reemitas, porque podrías duplicarlo. Búscalo en el seguimiento y escribe a [soporte](#como-pedir-soporte) con el `idOperacion`. | No, hasta que soporte lo confirme | | 5001 | `error_interno` | `error` | Escribe a [soporte](#como-pedir-soporte) con el `idOperacion` antes de reemitir. | No, hasta que soporte lo confirme | | 6001 | `operacion_cancelada` | `cancelado` | Emite de nuevo con claves nuevas. | Sí, con el mismo número | Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo; uno `cancelado` no lo consume, y al reenviarlo con claves nuevas se cuenta el nuevo envío. Si recibes un código que no está en esta tabla, trátalo como un rechazo que debe revisar una persona. ## Respuestas de error de `/v1` Todas las respuestas de error de `/v1` traen el mismo sobre con `estado`, `codEstado`, `msgError` y `errores`, y las cabeceras `X-Correlation-Id` y `X-Api-Version`, aunque la petición no haya llegado a un endpoint. La emisión es la excepción: sus rechazos traen la misma forma que su respuesta 202, con la información de la operación. | HTTP | codEstado | Cuándo ocurre | Qué hacer | |---|---|---|---| | 404 | 3013 | La ruta no existe: hay un error de escritura, falta `/v1` o un `{idOperacion}` no es un UUID. | Revisa la ruta contra la guía del endpoint. | | 405 | 3003 | Usaste un método HTTP que la ruta no admite, por ejemplo `GET` en la emisión. | Usa el método documentado. | | 415 | 3003 | Enviaste un cuerpo sin `Content-Type: application/json`, `application/xml` o `text/xml`, por ejemplo con `text/plain` o sin la cabecera. | Agrega el `Content-Type` que corresponda al cuerpo. | ## Errores por situación ### Al autenticar Estas son las causas por las que una ruta `/v1` rechaza la autenticación. Si coinciden varias, la respuesta informa de una sola. | codEstado | HTTP | Causa | Qué hacer | |---|---|---|---| | 3007 (`version_no_soportada`) | 400 | `X-Api-Version` inválida. | Envía `2026-11-16` o no envíes la cabecera. | | 3009 (`credenciales_invalidas`) | 401 | La API Key falta, no existe, está revocada, venció o es de otro ambiente. | Revisa la cabecera y la API Key. | | 3010 (`ip_no_autorizada`) | 403 | En producción, la API Key es válida, pero la IP no está permitida o no se pudo identificar. | Registra tu IP pública de producción. El sandbox no exige IP registrada. | | 5005 (`limite_solicitudes`) | 429 | Tu IP acumuló 20 autenticaciones fallidas en el minuto, o superaste las solicitudes por minuto de tu integración. | Espera los segundos que indica `Retry-After`. | ### Al emitir En cada endpoint de emisión por tipo, como `POST /v1/contribuyentes/{identificacion}/facturas`, la API responde con uno de estos resultados. Si coinciden varias causas, la respuesta informa de una sola; corrige y vuelve a enviar hasta recibir el 202. La ruta fija el tipo de comprobante: elige la ruta del tipo que emites y no envíes `infoTributaria.tipoDocumento` en el cuerpo, ni siquiera con el valor de la ruta, porque la API responde 422 con 3002 y lo señala como campo no soportado. Todas estas respuestas tienen la forma de la emisión que se describe en [Forma del error](#forma-del-error): | codEstado | HTTP | Causa | Consume cupo | |---|---|---|---| | 3006 | 413 | El cuerpo supera 2 MiB. | No | | 3003 | 415 | El `Content-Type` no es JSON ni XML. | No | | 3003 | 400 | El JSON o el XML está mal formado, o la `Idempotency-Key` falta o es inválida. | No | | 3002 | 422 | La estructura, un formato o una regla fiscal del comprobante no se cumplen, o el cuerpo trae un campo que la ruta no admite, como `infoTributaria.tipoDocumento`. | Sí, 1 documento como intento | | 3011 | 403 | El contribuyente, el tipo de comprobante o el servicio no están habilitados, o `infoTributaria.ruc` no corresponde al contribuyente. | No | | 3005 | 409 | Usaste la misma `Idempotency-Key` o `referenciaExterna` con otro cuerpo. | No | | 3004 | 409 | El número ya está registrado en un comprobante `recibido`, `autorizado` o rechazado por el SRI. | No | | 4004 | 429 | El cupo está agotado. | No | | 1001 o 1002 | 202 | La API recibió la emisión, o es un reintento idempotente de una emisión ya recibida. El cuerpo trae `estado` en `recibido`, el `idOperacion` y la `urlEstado`, que también llega en la cabecera `Location`. | Se consume cuando el SRI autoriza o rechaza el comprobante; un reintento idempotente no consume otro documento | | 3001, 4001, 4002 o 4003 | 422 | La emisión directa ya conoce un rechazo definitivo (`rechazado` o `rechazo_configuracion`). El cuerpo trae el `codEstado`, el `msgError`, el detalle en `errores`, el `idOperacion` y la `urlEstado`. | Depende del caso: consulta [Consumo y cuotas](/v1/guias/consumo) | | 5002 o 5001 | 503 o 500 | Tuvimos una falla temporal. Reintenta con la misma `Idempotency-Key`. | No | Un 202 significa que la solicitud fue **recibida**, no que el SRI la autorizó. Si el comprobante no llega a autorizarse, el resultado llega después en el [seguimiento](/v1/guias/consulta-operacion) o en un webhook, con el `estado` final y uno de los [códigos de resultado](#codigos-de-resultado-de-una-operacion); no es un error HTTP. El recorrido completo está en [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida). ### Al consultar | Endpoint | codEstado | HTTP | Causa | |---|---|---|---| | `GET /v1/operaciones/{idOperacion}` | 3013 | 404 | La operación no existe o es de otra integración o de otro ambiente. | | `GET /v1/consumo` | 3013 | 404 | Tu integración no tiene paquetes en este ambiente. | | `GET /v1/operaciones` | 3003 o 3012 | 400 | Falta `identificacion` o un filtro está fuera de rango, como se explica en [Límites](/v1/guias/limites#consultas). | | `GET /v1/catalogos/{nombre}` | 3013 | 404 | No existe un catálogo con esa clave. | | `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}` | 5002 | 503 | Los catálogos no están disponibles por un momento. Reintenta con espera. | | `GET /estado` | 5005 | 429 | Tu IP superó las 60 consultas por minuto. | | `GET /v1/consultas/...` | 3003 o 3012 | 400 | Falta un dato obligatorio o un filtro está fuera de rango. | | `GET /v1/consultas/...` | 3013 | 404 | El SRI no tiene datos para esa consulta. | | `GET /v1/consultas/...` | 5003, 5004 o 5005 | 502, 504 o 429 | El servicio de consulta falló, no respondió o limitó las solicitudes. | ### Al descargar archivos | Endpoint | codEstado | HTTP | Causa | |---|---|---|---| | `GET .../comprobantes/{claveAcceso}/ride` y `.../xml` | 3003 | 400 | La clave de acceso no tiene un formato válido de 49 dígitos. | | `GET .../comprobantes/{claveAcceso}/ride` | 3013 | 404 | El comprobante no existe para ese contribuyente, el RIDE aún no está disponible o el contribuyente es de marca blanca y no tiene RIDE. | | `GET .../comprobantes/{claveAcceso}/ride` y `.../xml` | 5004 | 504 | Nuestro servicio que entrega el archivo no respondió a tiempo. Reintenta con espera. | | `GET .../comprobantes/{claveAcceso}/ride` y `.../xml` | 5003 | 502 | Nuestro servicio que entrega el archivo devolvió un error. Reintenta con espera. | | `GET .../comprobantes/{claveAcceso}/xml` | 3013 | 404 | El comprobante no existe para ese contribuyente. | Por ejemplo, el RIDE de un contribuyente de marca blanca responde así: ```json { "estado": "rechazado", "codEstado": 3013, "msgError": "Recurso no encontrado.", "errores": [] } ``` ### Al gestionar el perfil del emisor | Endpoint | codEstado | HTTP | Causa | |---|---|---|---| | `GET` y `PUT .../perfil`, `POST .../perfil/logo` | 3011 | 403 | El contribuyente no está habilitado para tu integración. | | `PUT .../perfil` | 3003 | 400 | El JSON está mal formado o incluye un campo que no es editable. | | `POST .../perfil/logo` | 3003 | 400 | Falta el archivo, está vacío, supera 512 KB o no es PNG ni JPEG. | | `PUT .../perfil` y `POST .../perfil/logo` | 3006 | 413 | El cuerpo supera 1 MiB. | | `GET` y `PUT .../perfil`, `POST .../perfil/logo` | 5003 o 5004 | 502 o 504 | El servicio del perfil devolvió un error o no respondió a tiempo. | El detalle y los ejemplos están en [Perfil del emisor](/v1/guias/perfil-emisor#estados-de-este-endpoint). ## Maneja los errores en tu código El ejemplo envía una factura al endpoint de su tipo y decide qué hacer según el estado HTTP y el `codEstado`, leyendo también `msgError`, `errores` y la cabecera `X-Correlation-Id`. Ante el 202 acepta los dos códigos de `recibido`, 1001 y 1002, y guarda la `claveAcceso` solo si no llega en `null`. Para ejecutarlo, guarda el JSON de [Factura](/v1/guias/emision-01) como `comprobante.json`; el cuerpo no lleva `infoTributaria.tipoDocumento`, porque la ruta fija el tipo. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. ```bash # -i muestra las cabeceras: busca X-Correlation-Id y, en un 429, Retry-After. # El cuerpo trae estado, codEstado, msgError (solo si hay error) y errores. curl -s -i -X POST \ "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \ -H "X-Api-Key: $ECUAFACT_API_KEY" \ -H "Idempotency-Key: FACTURA-2026-0001" \ -H "Content-Type: application/json" \ -d @comprobante.json ``` ```csharp using System.Collections.Generic; using System.Linq; using System.Net.Http; using System.Text; using System.Text.Json; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas"); peticion.Headers.Add("Idempotency-Key", "FACTURA-2026-0001"); peticion.Content = new StringContent( await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json"); using HttpResponseMessage respuesta = await http.SendAsync(peticion); int estado = (int)respuesta.StatusCode; string correlacion = respuesta.Headers.TryGetValues("X-Correlation-Id", out IEnumerable? valores) ? valores.First() : ""; string cuerpo = await respuesta.Content.ReadAsStringAsync(); int codEstado = 0; string msgError = ""; List errores = new(); string? claveAcceso = null; if (cuerpo.Length > 0) { using JsonDocument json = JsonDocument.Parse(cuerpo); JsonElement raiz = json.RootElement; codEstado = raiz.TryGetProperty("codEstado", out JsonElement cod) ? cod.GetInt32() : 0; msgError = raiz.TryGetProperty("msgError", out JsonElement msg) ? msg.GetString() ?? "" : ""; if (raiz.TryGetProperty("errores", out JsonElement lista)) { foreach (JsonElement item in lista.EnumerateArray()) { errores.Add(item.GetString() ?? ""); } } if (raiz.TryGetProperty("claveAcceso", out JsonElement clave) && clave.ValueKind == JsonValueKind.String) { claveAcceso = clave.GetString(); } } if (estado == 202) { // 1001: todavia sin clave de acceso. 1002: ya trae claveAcceso. Console.WriteLine($"Recibido ({codEstado}). Clave de acceso: {claveAcceso ?? "pendiente"}"); return; } Console.WriteLine($"HTTP {estado} {codEstado}: {msgError} (X-Correlation-Id: {correlacion})"); foreach (string detalle in errores) { Console.WriteLine($" - {detalle}"); } string accion = (estado, codEstado) switch { (400, _) or (413, _) or (415, _) or (422, _) => "Corrige la solicitud y vuelve a enviarla.", (401, _) => "Revisa la API Key y la IP registrada.", (403, _) => "Revisa el contribuyente y el tipo de comprobante en /v1/contexto.", (409, 3004) => "El numero ya existe: busca el comprobante existente.", (409, _) => "Reenvia el cuerpo original o usa una Idempotency-Key nueva para otra emision.", (429, 4004) => "Cupo agotado: amplialo antes de seguir. No reintentes.", (429, _) => $"Espera {respuesta.Headers.RetryAfter?.Delta?.TotalSeconds ?? 60} s y reintenta con la misma Idempotency-Key.", (>= 500, _) => "Reintenta con la misma Idempotency-Key y espera exponencial.", _ => "Revisa el catalogo de errores." }; Console.WriteLine(accion); ``` ```python import json import os import requests with open("comprobante.json", encoding="utf-8") as archivo: cuerpo = json.load(archivo) r = requests.post( "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas", headers={ "X-Api-Key": os.environ["ECUAFACT_API_KEY"], "Idempotency-Key": "FACTURA-2026-0001", }, json=cuerpo, timeout=30, ) correlacion = r.headers.get("X-Correlation-Id", "") respuesta = r.json() if r.content else {} cod_estado = respuesta.get("codEstado", 0) if r.status_code == 202: # 1001: todavia sin clave de acceso. 1002: ya trae claveAcceso. print(f"Recibido ({cod_estado}). Clave de acceso:", respuesta.get("claveAcceso") or "pendiente") else: msg_error = respuesta.get("msgError", "") errores = respuesta.get("errores", []) print(f"HTTP {r.status_code} {cod_estado}: {msg_error} (X-Correlation-Id: {correlacion})") for detalle in errores: print(" -", detalle) if r.status_code in (400, 413, 415, 422): print("Corrige la solicitud y vuelve a enviarla.") elif r.status_code == 401: print("Revisa la API Key y la IP registrada.") elif r.status_code == 403: print("Revisa el contribuyente y el tipo de comprobante en /v1/contexto.") elif r.status_code == 409 and cod_estado == 3004: print("El numero ya existe: busca el comprobante existente.") elif r.status_code == 409: print("Reenvia el cuerpo original o usa una Idempotency-Key nueva para otra emision.") elif r.status_code == 429 and cod_estado == 4004: print("Cupo agotado: amplialo antes de seguir. No reintentes.") elif r.status_code == 429: print(f"Espera {r.headers.get('Retry-After', '60')} s y reintenta con la misma Idempotency-Key.") elif r.status_code == 415: print("Tipo de contenido no admitido: envia JSON o XML.") elif r.status_code >= 500: print("Reintenta con la misma Idempotency-Key y espera exponencial.") ``` ```javascript // Node.js 18 o superior. Guarda como errores.mjs y ejecuta: node errores.mjs import { readFile } from 'node:fs/promises'; const res = await fetch( 'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas', { method: 'POST', headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY, 'Idempotency-Key': 'FACTURA-2026-0001', 'Content-Type': 'application/json' }, body: await readFile('comprobante.json', 'utf8') }); const correlacion = res.headers.get('X-Correlation-Id') ?? ''; const texto = await res.text(); const respuesta = texto ? JSON.parse(texto) : {}; const codEstado = respuesta.codEstado ?? 0; if (res.status === 202) { // 1001: todavia sin clave de acceso. 1002: ya trae claveAcceso. console.log(`Recibido (${codEstado}). Clave de acceso: ${respuesta.claveAcceso ?? 'pendiente'}`); } else { console.log(`HTTP ${res.status} ${codEstado}: ${respuesta.msgError ?? ''} (X-Correlation-Id: ${correlacion})`); for (const detalle of respuesta.errores ?? []) { console.log(' -', detalle); } if ([400, 413, 415, 422].includes(res.status)) { console.log('Corrige la solicitud y vuelve a enviarla.'); } else if (res.status === 401) { console.log('Revisa la API Key y la IP registrada.'); } else if (res.status === 403) { console.log('Revisa el contribuyente y el tipo de comprobante en /v1/contexto.'); } else if (res.status === 409 && codEstado === 3004) { console.log('El numero ya existe: busca el comprobante existente.'); } else if (res.status === 409) { console.log('Reenvia el cuerpo original o usa una Idempotency-Key nueva para otra emision.'); } else if (res.status === 429 && codEstado === 4004) { console.log('Cupo agotado: amplialo antes de seguir. No reintentes.'); } else if (res.status === 429) { console.log(`Espera ${res.headers.get('Retry-After') ?? '60'} s y reintenta con la misma Idempotency-Key.`); } else if (res.status === 415) { console.log('Tipo de contenido no admitido: envia JSON o XML.'); } else if (res.status >= 500) { console.log('Reintenta con la misma Idempotency-Key y espera exponencial.'); } } ``` ```php true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'), 'Idempotency-Key: FACTURA-2026-0001', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'), CURLOPT_HEADERFUNCTION => function ($ch, $linea) use (&$cabecerasRespuesta) { $partes = explode(':', $linea, 2); if (count($partes) === 2) { $cabecerasRespuesta[strtolower(trim($partes[0]))] = trim($partes[1]); } return strlen($linea); }, ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $correlacion = $cabecerasRespuesta['x-correlation-id'] ?? ''; $respuesta = $cuerpo ? json_decode($cuerpo, true) : []; $codEstado = (int) ($respuesta['codEstado'] ?? 0); if ($estado === 202) { // 1001: todavia sin clave de acceso. 1002: ya trae claveAcceso. echo "Recibido ($codEstado). Clave de acceso: " . ($respuesta['claveAcceso'] ?? 'pendiente') . PHP_EOL; exit; } echo "HTTP $estado $codEstado: " . ($respuesta['msgError'] ?? '') . " (X-Correlation-Id: $correlacion)" . PHP_EOL; foreach ($respuesta['errores'] ?? [] as $detalle) { echo ' - ' . $detalle . PHP_EOL; } if (in_array($estado, [400, 413, 415, 422], true)) { echo 'Corrige la solicitud y vuelve a enviarla.' . PHP_EOL; } elseif ($estado === 401) { echo 'Revisa la API Key y la IP registrada.' . PHP_EOL; } elseif ($estado === 403) { echo 'Revisa el contribuyente y el tipo de comprobante en /v1/contexto.' . PHP_EOL; } elseif ($estado === 409 && $codEstado === 3004) { echo 'El numero ya existe: busca el comprobante existente.' . PHP_EOL; } elseif ($estado === 409) { echo 'Reenvia el cuerpo original o usa una Idempotency-Key nueva para otra emision.' . PHP_EOL; } elseif ($estado === 429 && $codEstado === 4004) { echo 'Cupo agotado: amplialo antes de seguir. No reintentes.' . PHP_EOL; } elseif ($estado === 429) { echo 'Espera ' . ($cabecerasRespuesta['retry-after'] ?? '60') . ' s y reintenta con la misma Idempotency-Key.' . PHP_EOL; } elseif ($estado === 415) { echo 'Tipo de contenido no admitido: envia JSON o XML.' . PHP_EOL; } elseif ($estado >= 500) { echo 'Reintenta con la misma Idempotency-Key y espera exponencial.' . PHP_EOL; } ``` ```csharp-sdk using Ecuafact.Sdk; using Ecuafact.Sdk.Contracts; // client: cliente EcuafactClient - ver SDK .NET. comprobante: tu Estructura del comprobante. try { EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001"); Console.WriteLine($"Recibido ({resultado.Admission.CodEstado}): {resultado.Admission.IdOperacion}"); } catch (EcuafactApiException ex) { Console.WriteLine($"HTTP {ex.EstadoHttp} {ex.CodEstado}: {ex.MsgError} (X-Correlation-Id: {ex.CorrelationId})"); foreach (string detalle in ex.Errores) { Console.WriteLine($" - {detalle}"); } if (ex.CodEstado == CodEstado.CupoAgotado) { Console.WriteLine("Cupo agotado: amplialo antes de seguir. No reintentes."); } } ``` ```python-sdk from ecuafact import CodEstado, EcuafactApiException # client: cliente EcuafactClient - ver SDK Python. comprobante: tu Estructura del comprobante. try: resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001") print(f"Recibido ({resultado.admission.cod_estado}):", resultado.admission.id_operacion) except EcuafactApiException as ex: print(f"HTTP {ex.estado_http} {ex.cod_estado}: {ex.msg_error} (X-Correlation-Id: {ex.correlation_id})") for detalle in ex.errores: print(" -", detalle) if ex.cod_estado == CodEstado.CUPO_AGOTADO: print("Cupo agotado: amplialo antes de seguir. No reintentes.") ``` ```javascript-sdk import { CodEstado, EcuafactApiException } from "@ecuafact/sdk"; // client: cliente EcuafactClient - ver SDK Node.js. comprobante: tu Estructura del comprobante. try { const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001"); console.log(`Recibido (${resultado.admission.codEstado}):`, resultado.admission.idOperacion); } catch (ex) { if (!(ex instanceof EcuafactApiException)) throw ex; console.log(`HTTP ${ex.estadoHttp} ${ex.codEstado}: ${ex.msgError} (X-Correlation-Id: ${ex.correlationId})`); for (const detalle of ex.errores) console.log(" -", detalle); if (ex.codEstado === CodEstado.CupoAgotado) console.log("Cupo agotado: amplialo antes de seguir. No reintentes."); } ``` ```php-sdk emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001'); echo "Recibido ({$resultado->admission->codEstado}): " . $resultado->admission->idOperacion . PHP_EOL; } catch (EcuafactApiException $ex) { echo "HTTP {$ex->estadoHttp} {$ex->codEstado}: {$ex->msgError} (X-Correlation-Id: {$ex->correlationId})" . PHP_EOL; foreach ($ex->errores as $detalle) { echo ' - ' . $detalle . PHP_EOL; } if ($ex->codEstado === CodEstado::CUPO_AGOTADO) { echo 'Cupo agotado: amplialo antes de seguir. No reintentes.' . PHP_EOL; } } ``` ```java-sdk import com.ecuafact.sdk.EcuafactApiException; import com.ecuafact.sdk.EmisionResultado; import com.ecuafact.sdk.contracts.CodEstado; // client: cliente EcuafactClient - ver SDK Java. comprobante: tu Estructura del comprobante. try { EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001"); System.out.println("Recibido (" + resultado.admission().codEstado() + "): " + resultado.admission().idOperacion()); } catch (EcuafactApiException ex) { System.out.println("HTTP " + ex.estadoHttp() + " " + ex.codEstado() + ": " + ex.msgError() + " (X-Correlation-Id: " + ex.correlationId() + ")"); ex.errores().forEach(detalle -> System.out.println(" - " + detalle)); if (ex.codEstado() == CodEstado.CUPO_AGOTADO) { System.out.println("Cupo agotado: amplialo antes de seguir. No reintentes."); } } ``` Si usas nuestros SDK oficiales, no necesitas programar estos reintentos: reintentan solos, con la misma `Idempotency-Key`, los cortes de red y los estados 408, 425, 500, 502, 503 y 504, hasta 3 intentos en total y respetando `Retry-After`. Un 429 con el `codEstado` 5005 también se reintenta por defecto, y puedes desactivarlo con la opción de reintento por límite del SDK: `RetryRateLimited` en .NET, `retry_rate_limited` en Python y `retryRateLimited` en Node.js, PHP y Java. Un 429 con el `codEstado` 4004 no se reintenta nunca. La excepción llega cuando se agotan los intentos o cuando el error no se reintenta; el detalle está en [SDKs](/v1/guias/sdk). ## Cómo pedir soporte Abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/). También puedes consultar el [centro de ayuda](https://ecuafact.com/ayuda/), escribir por [WhatsApp](https://wa.me/593988315544) o usar la [página de contacto](https://ecuafact.com/contacto). Horario: lunes a viernes, 09:00-18:00 GMT-5. Primera respuesta: 1 día hábil; producción caída: 4 horas. Si necesitas ayuda, incluye estos datos; con ellos podemos ubicar tu caso sin más idas y vueltas: - [ ] El `X-Correlation-Id` de la respuesta, que es el dato más importante. - [ ] El valor de `X-Additional-Info`, si lo enviaste. Podemos buscar tu solicitud por ese texto aunque no tengas el `X-Correlation-Id`, como se explica en [Identifica tus solicitudes](/v1/guias/buenas-practicas#identifica-tus-solicitudes). - [ ] La fecha y la hora aproximadas de la petición. - [ ] La URL completa de la petición, que indica el ambiente. - [ ] El estado HTTP, el `codEstado`, el `msgError` y los `errores` recibidos. - [ ] El `idOperacion`, si la emisión llegó a responder 202, y el `codEstado` de la operación si no terminó autorizada. - [ ] El cuerpo que enviaste, **sin** la API Key. No hace falta adjuntar capturas de pantalla. > [!WARNING] > Nunca incluyas tu API Key ni el secreto de tus webhooks en un ticket, un correo > o un chat de soporte. No los necesitamos para ayudarte. ## Siguientes pasos - [Buenas prácticas](/v1/guias/buenas-practicas): reintentos con espera exponencial e idempotencia, con código listo para copiar. - [Límite de request](/v1/guias/limite-de-request): cómo leer `Retry-After` y las cabeceras `X-RateLimit-*`. - [Comprobantes electrónicos](/v1/guias/emision): las reglas de la Estructura del comprobante que evitan un 422. - [Respuestas del API](/v1/guias/respuestas): forma de las respuestas exitosas y cabeceras comunes. --- # Catálogos Los códigos del SRI que lleva la Estructura del comprobante, con el campo donde va cada uno y las reglas que valida la API. Muchos campos del comprobante no admiten texto libre, sino un código del SRI: el tipo de identificación del comprador, la tarifa de IVA, la forma de pago o el código de retención. Aquí tienes esos códigos en tablas, en qué campo va cada uno y qué reglas comprueba la API antes de aceptar el comprobante. Los catálogos que cambian con la normativa, como las tarifas, las formas de pago o los tipos de identificación, también los puedes leer desde la API, como se explica en [Consultar los catálogos por API](#consultar-los-catalogos-por-api). Las tablas de esta página son la referencia legible y la API es la fuente que tu sistema puede consultar para mantenerse al día. Los términos del dominio, como [RUC](/v1/guias/glosario), [retención](/v1/guias/glosario) o [sustento](/v1/guias/glosario), están explicados en el [Glosario](/v1/guias/glosario). ## Consultar los catálogos por API Puedes leer los catálogos del SRI directamente desde la API para llenar listas desplegables, validar un código antes de emitir o enterarte de una tarifa nueva sin esperar a que cambie tu sistema. La consulta no consume cupo y se hace en dos pasos: primero listas los catálogos disponibles y después lees el detalle del que necesitas. | Operación | Ruta | Qué devuelve | |---|---|---| | Listar catálogos | `GET /v1/catalogos` | La clave y una descripción breve de cada catálogo. | | Leer un catálogo | `GET /v1/catalogos/{nombre}` | Las filas del catálogo con su código, descripción y, según el catálogo, su valor, su vigencia y atributos propios. | Ambas operaciones requieren la cabecera `X-Api-Key`, no llevan cuerpo y responden con `Cache-Control: private, max-age=3600`. Los catálogos cambian pocas veces al año, así que puedes guardar la respuesta hasta una hora. ### Catálogos disponibles `nombre` es la clave que devuelve `GET /v1/catalogos`. Estos son los catálogos publicados: | Clave | Contenido | Dónde se usa | |---|---|---| | `tipos-comprobante` | Tipos de comprobante electrónico y su código. | [Tipos de comprobante](#tipos-de-comprobante) | | `tipos-identificacion` | Tipos de identificación del comprador, proveedor, transportista o sujeto retenido. | [Tipos de identificación](#tipos-de-identificacion) | | `impuestos` | Códigos de impuesto de los comprobantes con importes. | [Impuestos](#impuestos) | | `tarifas-iva` | Valores de `codigoPorcentaje` para el IVA y su tarifa en porcentaje. | [Tarifas de IVA](#tarifas-de-iva) | | `formas-pago` | Formas de pago de `pagos[].formaPago`. | [Formas de pago](#formas-de-pago) | | `retencion-iva` | Códigos de retención de IVA y su porcentaje. | [Códigos de retención de IVA](#codigos-de-retencion-de-iva) | | `retencion-isd` | Códigos de retención del impuesto a la salida de divisas (ISD), con su porcentaje y vigencia. | [Retenciones y sustento](#retenciones-y-sustento) | | `ambientes` | Tipos de ambiente de emisión. | [Tipo de emisión y ambiente](#tipo-de-emision-y-ambiente) | | `tipos-emision` | Tipos de emisión. | [Tipo de emisión y ambiente](#tipo-de-emision-y-ambiente) | | `restricciones` | Tipo, longitud, patrón y decimales de los campos del comprobante según los XSD del SRI. | [Límites](/v1/guias/limites#estructura-del-comprobante) | ### Ejemplo > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. El ejemplo lee el detalle del catálogo `tarifas-iva`. Para listar todos los catálogos, llama a `GET /v1/catalogos` sin el último segmento de la ruta. ```bash curl -s "https://api-sandbox.mynexusapi.com/v1/catalogos/tarifas-iva" \ -H "X-Api-Key: $ECUAFACT_API_KEY" ``` ```csharp using System.Net.Http; string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!; using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") }; http.DefaultRequestHeaders.Add("X-Api-Key", apiKey); using HttpResponseMessage respuesta = await http.GetAsync("/v1/catalogos/tarifas-iva"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```javascript // Node.js 18 o superior. Guarda como catalogos.mjs y ejecuta: node catalogos.mjs const res = await fetch('https://api-sandbox.mynexusapi.com/v1/catalogos/tarifas-iva', { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } }); console.log(res.status, await res.text()); ``` ```php true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')], ]); $cuerpo = curl_exec($ch); $estado = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $estado . ' ' . $cuerpo . PHP_EOL; ``` ```bash-cli # Resultado esperado: la tabla de códigos del catálogo, con su descripción y valor. ecuafact catalogos tarifas-iva --entorno sandbox ``` La respuesta de `GET /v1/catalogos` es el índice: ```json { "catalogos": [ { "nombre": "tipos-comprobante", "descripcion": "Tipos de comprobante electrónico y su código codDoc." }, { "nombre": "tarifas-iva", "descripcion": "Valores de codigoPorcentaje para el IVA y su tarifa en porcentaje." } ] } ``` | Campo | Tipo | Descripción | |---|---|---| | `catalogos` | array | Los catálogos disponibles, en el orden de la ficha técnica del SRI. | | `catalogos[].nombre` | string | Clave del catálogo; es el valor que va en la ruta de detalle. | | `catalogos[].descripcion` | string | Descripción breve de lo que contiene. | La respuesta de `GET /v1/catalogos/{nombre}` es el detalle: ```json { "nombre": "tarifas-iva", "descripcion": "Valores de codigoPorcentaje para el IVA y su tarifa en porcentaje.", "fuente": "Ficha técnica SRI 2.34, Tabla 17", "items": [ { "codigo": "0", "descripcion": "0 %", "valor": 0 }, { "codigo": "4", "descripcion": "15 %", "valor": 15 } ] } ``` | Campo | Tipo | Descripción | |---|---|---| | `nombre` | string | Clave del catálogo. | | `descripcion` | string | Descripción breve del catálogo. | | `fuente` | string | Tabla o anexo de la ficha técnica del SRI de donde proviene. | | `items` | array | Las filas del catálogo. | | `items[].codigo` | string | Código tal como va en el comprobante. Envíalo como texto, con sus ceros a la izquierda cuando los tenga. | | `items[].descripcion` | string | Descripción del código. | | `items[].valor` | number | Valor numérico asociado, por ejemplo la tarifa en porcentaje. Se omite si el catálogo no lo tiene. | | `items[].vigenteDesde` | string | Primer día de vigencia, en formato `yyyy-MM-dd`. Se omite si la fila no está acotada por el inicio. | | `items[].vigenteHasta` | string | Último día de vigencia, en formato `yyyy-MM-dd`. Se omite si la fila sigue vigente. | | `items[].atributos` | objeto | Atributos propios del catálogo, por ejemplo la raíz del XML en `tipos-comprobante`. Se omite si no hay. | Un mismo `codigo` puede aparecer en varias filas con vigencias distintas, como ocurre con los códigos de retención del ISD. Elige la fila cuya vigencia cubre la fecha de tu comprobante. ### Estados de este endpoint | Código | HTTP | Cuándo ocurre | Qué hacer | |---|---|---|---| | 3009 (`credenciales_invalidas`) | 401 | Falta `X-Api-Key` o la API Key es inválida, está revocada o venció. | Revisa la cabecera y la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). | | 3010 (`ip_no_autorizada`) | 403 | En producción, la IP de origen no está registrada para tu integración. | Registra tu IP pública en el Portal del Cliente. | | 3013 (`no_encontrado`) | 404 | `GET /v1/catalogos/{nombre}` no encuentra un catálogo con esa clave. | Lista los catálogos con `GET /v1/catalogos` y usa una clave de la lista. | | 5005 (`limite_solicitudes`) | 429 | Superaste las solicitudes por minuto de tu integración. | Espera los segundos que indica `Retry-After` y repite la consulta. | | 5002 (`servicio_no_disponible`) | 503 | Los catálogos no están disponibles por un momento. | Espera los segundos que indica `Retry-After` y repite la consulta. | ## Emisión ### Tipos de comprobante Estos son los códigos de tipo de comprobante. El tipo lo fija la ruta de emisión que llamas, así que el cuerpo no lleva `infoTributaria.tipoDocumento`. En las respuestas y en los filtros de consulta, el tipo se identifica con `tipoDocumento`. Los códigos también se usan en `info.codDocModificado`, en las notas de crédito y débito, para indicar el tipo del documento modificado. | Código | Comprobante | Ruta de emisión | Guía | |---|---|---|---| | `01` | Factura | `POST /v1/contribuyentes/{identificacion}/facturas` | [Factura](/v1/guias/emision-01) | | `03` | Liquidación de compra de bienes y prestación de servicios | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra` | [Liquidación de compra](/v1/guias/emision-03) | | `04` | Nota de crédito | `POST /v1/contribuyentes/{identificacion}/notas-credito` | [Nota de crédito](/v1/guias/emision-04) | | `05` | Nota de débito | `POST /v1/contribuyentes/{identificacion}/notas-debito` | [Nota de débito](/v1/guias/emision-05) | | `06` | Guía de remisión | `POST /v1/contribuyentes/{identificacion}/guias-remision` | [Guía de remisión](/v1/guias/emision-06) | | `07` | Comprobante de retención | `POST /v1/contribuyentes/{identificacion}/retenciones` | [Comprobante de retención](/v1/guias/emision-07) | Que tu API Key pueda emitir un tipo depende de los tipos habilitados para tu integración. Los tipos habilitados aparecen en `tiposComprobante` de [`GET /v1/contexto`](/v1/guias/consulta-contexto). ### Tipos de identificación Estos códigos van en `tipoIdentificacionComprador` (factura y notas), `tipoIdentificacionProveedor` (liquidación de compra), `tipoIdentificacionTransportista` (guía) y `tipoIdentificacionSujetoRetenido` (retención). Con cualquier otro código, la API responde 422. | Código | Tipo | Regla de la identificación | |---|---|---| | `04` | RUC | 13 dígitos. | | `05` | Cédula | 10 dígitos. | | `06` | Pasaporte | Hasta 20 caracteres. | | `07` | Venta a consumidor final | Identificación `9999999999999`. Solo en factura y con `importeTotal` de hasta 50.00. | | `08` | Identificación del exterior | Hasta 20 caracteres. | Además, cada tipo de comprobante tiene sus propias restricciones: | Comprobante | Restricción | |---|---| | Factura (`01`) | Admite `07` solo si `importeTotal` es 50.00 o menos. Por encima, identifica al comprador con `04`, `05`, `06` u `08`. | | Liquidación, notas de crédito y débito, retención | No admiten `07`, porque el receptor debe estar identificado. | | Guía de remisión | El destinatario no lleva tipo, y `identificacionDestinatario` debe tener 10 dígitos (cédula) o 13 (RUC). | ### Impuestos El código del impuesto va en `impuestos[].codigo` y `totalConImpuestos[].codigo` en los comprobantes con importes, y en `impuestosDocSustento[].codImpuestoDocSustento` en la retención. | Código | Impuesto | Soportado por la API | |---|---|---| | `2` | IVA | Sí. Cada detalle lleva exactamente un IVA. | | `3` | ICE | Sí, solo el ICE porcentual y como máximo uno por detalle. La nota de débito y la liquidación de compra no admiten ICE. | | `5` | IRBPNR | No. Un detalle con IRBPNR recibe un 422. | ### Tarifas de IVA Estos son los valores de `codigoPorcentaje` cuando `codigo` es `2` (IVA). La `tarifa` que envías es el porcentaje, es decir, `15` y no `0.15`. | codigoPorcentaje | Tarifa | `tarifa` que envías | Uso | |---|---|---|---| | `0` | 0 % | `0` | Bienes y servicios gravados con tarifa 0 %. | | `4` | 15 % | `15` | Tarifa general vigente. | | `5` | 5 % | `5` | Tarifa reducida (por ejemplo, materiales de construcción). | | `6` | No objeto de impuesto | `0` | Operaciones que no son objeto de IVA. | | `7` | Exento de IVA | `0` | Operaciones exentas. | | `8` | 8 % (diferenciado) | `8` | Tarifa diferenciada que fija el SRI para periodos específicos (por ejemplo, feriados turísticos). | | `2` | 12 % | `12` | Tarifa del SRI para operaciones de los periodos fiscales en que rige el 12 %. | | `3` | 14 % | `14` | Tarifa del SRI para operaciones de los periodos fiscales en que rige el 14 %. | | `10` | 13 % | `13` | Tarifa especial publicada por el SRI. | El catálogo del SRI incluye códigos de periodos anteriores: su presencia no determina que correspondan a la fecha y operación que estás facturando. La API valida estas reglas y, si alguna no se cumple, responde 422: - El `codigoPorcentaje` es uno de la tabla anterior y la `tarifa` es la que corresponde a ese código. Con otro código, la API responde 422. - La `tarifa` admite 2 decimales como máximo y no supera 99.99. - Con `codigoPorcentaje` en `0`, `6` o `7`, la `tarifa` es 0. - Con cualquier otro `codigoPorcentaje`, la `tarifa` es mayor que 0. - El `valor` es (`cantidad` x `precioUnitario` - `descuento`) x `tarifa` / 100, calculado sobre la base **sin redondear** y redondeado a 2 decimales al final. Como `baseImponible` reporta la base ya redondeada, `baseImponible` x `tarifa` / 100 puede diferir en un centavo. El ejemplo y el detalle están en [Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales). - La base del IVA incluye el ICE de la misma línea, si lo hay. - En la cabecera (`totalConImpuestos`), la `tarifa` es opcional, pero si la envías debe coincidir con la de los detalles del mismo `codigoPorcentaje`. ### Tarifas de ICE Estos son los valores de `codigoPorcentaje` cuando `codigo` es `3` (ICE). El SRI publica un código de hasta 4 dígitos por cada producto gravado, como cigarrillos, bebidas alcohólicas, vehículos o perfumes, y los actualiza con frecuencia. La `tarifa` no se publica: debes determinar el porcentaje aplicable al producto y fecha antes de emitir. La API solo admite el ICE **porcentual**, cuyo `valor` es la base de la línea x `tarifa` / 100, y ese valor se suma a la base del IVA de la misma línea. El ICE de tarifa específica, que es un valor fijo por unidad, no está soportado. ### Formas de pago Estos son los códigos de `pagos[].formaPago`, de 2 dígitos. | Código | Forma de pago | |---|---| | `01` | Sin utilización del sistema financiero (efectivo) | | `15` | Compensación de deudas | | `16` | Tarjeta de débito | | `17` | Dinero electrónico | | `18` | Tarjeta prepago | | `19` | Tarjeta de crédito | | `20` | Otros con utilización del sistema financiero (transferencia, cheque) | | `21` | Endoso de títulos | Cualquier otro código responde 422. Cada comprobante con pagos lleva de 1 a 20 formas de pago, y la suma de `pagos[].total` debe ser igual al total del comprobante. Si `plazo` es mayor que 0, `unidadTiempo` es obligatoria, como se explica en [Unidades de tiempo](#unidades-de-tiempo). ### Retenciones y sustento Estos son los códigos del [Comprobante de retención](/v1/guias/emision-07). El impuesto retenido va en `retenciones[].codigo`: | `codigo` | Impuesto retenido | Base de la retención | Tabla de `codigoRetencion` | |---|---|---|---| | `1` | Impuesto a la renta | Base sin IVA de la compra | [Códigos de retención de renta](#codigos-de-retencion-de-renta) | | `2` | IVA | Valor del IVA de la compra | [Códigos de retención de IVA](#codigos-de-retencion-de-iva) | | `6` | Impuesto a la salida de divisas (ISD) | Valor pagado | `4580` (hasta abril de 2025) o `4586` (2.5 %, desde mayo de 2025) | Con cualquier otro `codigo`, la API responde 422. `codigoRetencion` admite hasta 5 caracteres (letras, dígitos y `- _ . : /`). `porcentajeRetener` admite 2 decimales como máximo y 3 dígitos en total: `100`, `70`, `10.5` y `2.75` son válidos y `12.75` responde 422. La API comprueba que `valorRetenido` sea `baseImponible` x `porcentajeRetener` / 100, redondeado a 2 decimales. En IVA (`codigo` `2`) comprueba además que el código exista y que el porcentaje corresponda al código; en ISD (`codigo` `6`) comprueba que el código sea `4580` o `4586`. En renta (`codigo` `1`) **no** comprueba que el porcentaje corresponda al código: si no corresponde, el SRI puede no autorizar el comprobante. ### Códigos de retención de IVA Estos son los valores de `retenciones[].codigoRetencion` cuando `codigo` es `2`. | codigoRetencion | Porcentaje (`porcentajeRetener`) | |---|---| | `9` | 10 | | `10` | 20 | | `1` | 30 | | `11` | 50 | | `2` | 70 | | `3` | 100 | | `7` | 0 (retención en cero) | | `8` | 0 (no procede retención) | ### Códigos de retención de renta Estos son valores de `retenciones[].codigoRetencion` cuando `codigo` es `1`. El SRI mantiene una tabla extensa que actualiza por resolución, así que aquí solo están las filas de uso frecuente con su porcentaje de referencia. Antes de usar un código, confirma el porcentaje en la tabla vigente del SRI. | codigoRetencion | Concepto | Porcentaje de referencia | |---|---|---| | `303` | Honorarios profesionales y demás pagos por servicios relacionados con el título profesional | 10 | | `307` | Servicios en los que predomina la mano de obra | 2 | | `310` | Transporte privado de pasajeros o servicio público o privado de carga | 1 | | `312` | Transferencia de bienes muebles de naturaleza corporal | 1.75 | | `320` | Arrendamiento de bienes inmuebles | 10 | | `322` | Seguros y reaseguros (primas y cesiones) | 1.75 | | `332` | Pagos de bienes o servicios no sujetos a retención | 0 | | `343` | Otras retenciones aplicables el 1 % | 1 | | `3440` | Otras retenciones aplicables el 2.75 % | 2.75 | La API no admite los códigos de banano `338`, `340`, `341`, `342`, `342A` y `342B`, que reciben un 422. ### Códigos de sustento `docsSustento[].codSustento` indica para qué usas la compra en tu contabilidad tributaria. Estas son las filas de uso frecuente: | codSustento | Descripción | Admitido | |---|---|---| | `01` | Crédito tributario para declaración de IVA (servicios y bienes distintos de inventarios y activos fijos) | Sí | | `02` | Costo o gasto para declaración de impuesto a la renta (servicios y bienes distintos de inventarios y activos fijos) | Sí | | `03` | Activo fijo: crédito tributario para declaración de IVA | Sí | | `04` | Activo fijo: costo o gasto para declaración de impuesto a la renta | Sí | | `05` | Liquidación de gastos de viaje, hospedaje y alimentación | Sí | | `06` | Inventario: crédito tributario para declaración de IVA | Sí | | `07` | Inventario: costo o gasto para declaración de impuesto a la renta | Sí | | `10` | Distribución de dividendos, beneficios o utilidades | No (422) | ### Tipos de documento de sustento `docsSustento[].codDocSustento` indica el tipo del documento del proveedor sobre el que retienes. Estas son las filas de uso frecuente: | codDocSustento | Documento | Admitido | |---|---|---| | `01` | Factura | Sí | | `02` | Nota o boleta de venta | Sí | | `03` | Liquidación de compra de bienes y prestación de servicios | Sí | | `04` | Nota de crédito | Sí | | `05` | Nota de débito | Sí | | `41` | Comprobante de venta emitido por reembolso | No (422) | El documento de sustento sigue estas reglas: | Campo | Regla | |---|---| | `numDocSustento` | Lleva 15 dígitos sin guiones (`001001000000123`), aunque también se acepta `ddd-ddd-ddddddddd`. | | `numAutDocSustento` | Es opcional. Si lo envías, es el número de autorización del sustento, de 10 a 49 dígitos (49 en un sustento electrónico: su clave de acceso). | | `pagoLocExt` | Vale `01` (pago local), porque el pago al exterior no está soportado. | ## Estados ### Estado de la operación Estos son los valores de `estado` en [`GET /v1/operaciones/{idOperacion}`](/v1/guias/consulta-operacion) y en el cuerpo de los [webhooks](/v1/guias/webhooks#campos-del-cuerpo). Todos son finales salvo `recibido`. | Estado | Significado | Final | |---|---|---| | `recibido` | Recibimos el comprobante, pasó nuestras validaciones y todavía no tiene un resultado final. Espera el webhook o consulta más tarde, sin reenviarlo. | No | | `autorizado` | El SRI autorizó el comprobante. Es el único valor con validez fiscal. | Sí | | `rechazado` | El comprobante no se autorizó por su contenido, porque lo rechazó el SRI o porque no cumplió una regla de la validación fiscal. Corrígelo según `codEstado` y `errores` y emítelo de nuevo. | Sí | | `rechazo_configuracion` | No se pudo emitir porque falta o está mal una configuración del emisor, como la firma electrónica o el cupo. Corrige la configuración y reenvíalo. | Sí | | `error` | No se pudo emitir por un fallo inesperado o porque algo impidió de forma definitiva su autorización. Lo que debes hacer depende de `codEstado`. | Sí | | `cancelado` | La plataforma canceló el envío de forma automática. El comprobante no se emitió y no consumió cupo. | Sí | No llames "autorizado" a un comprobante recibido, porque el 202 de la emisión solo indica que fue **recibido**. ### Códigos de resultado Cada `estado` viene acompañado de un `codEstado`, un número de 4 dígitos cuyo primer dígito es el propio `estado`. Con `recibido` el código es 1001, o 1002 si el comprobante ya tiene `claveAcceso`, y con `autorizado` es 2001; en esos casos `msgError` no viene y `errores` es una lista vacía. Cuando el `estado` es otro, el `codEstado` dice la causa, `msgError` la describe con un texto fijo y `errores` trae el detalle cuando existe. Qué hacer ante cada código se explica en [Errores](/v1/guias/errores#codigos-de-resultado-de-una-operacion). | `codEstado` | `estado` | Significado | |---|---|---| | 1001 (`comprobante_recibido`) | `recibido` | Recibimos el comprobante y todavía no tiene `claveAcceso`. | | 1002 (`comprobante_enviado`) | `recibido` | Recibimos el comprobante y ya tiene `claveAcceso`, pero aún no hay resultado del SRI. | | 2001 (`comprobante_autorizado`) | `autorizado` | El SRI autorizó el comprobante. | | 3001 (`rechazo_sri`) | `rechazado` | El SRI rechazó el comprobante. `errores` trae el mensaje del SRI. | | 3002 (`comprobante_invalido`) | `rechazado` | La validación fiscal rechazó el contenido antes de enviarlo al SRI. `errores` trae el detalle por campo cuando existe. | | 4001 (`emisor_no_configurado`) | `rechazo_configuracion` | Al emisor le falta configuración para emitir ante el SRI. | | 4002 (`firma_no_valida`) | `rechazo_configuracion` | La firma electrónica del emisor está caducada o no es válida. | | 4003 (`suscripcion_inactiva`) | `rechazo_configuracion` | El servicio de emisión de tu cuenta no está activo en este ambiente. | | 4004 (`cupo_agotado`) | `rechazo_configuracion` | No quedan documentos en tus paquetes vigentes. | | 5006 (`entrega_no_posible`) | `error` | El comprobante no se pudo emitir y confirmamos que no se creó. | | 5007 (`resultado_no_confirmado`) | `error` | No pudimos confirmar si el comprobante llegó a crearse. | | 5001 (`error_interno`) | `error` | Tuvimos un fallo inesperado. | | 6001 (`operacion_cancelada`) | `cancelado` | La plataforma canceló el envío y no consumió cupo. | ### Estado SRI de procesamiento Son las siglas que usa el SRI en sus propios servicios y portales. La API no las devuelve, sino que las resume en `estado`, pero te sirven si comparas con lo que ves en el portal del SRI. | Sigla | Significado | Equivale a `estado` | |---|---|---| | `PPR` | En procesamiento | `recibido` | | `AUT` | Autorizado | `autorizado` | | `NAT` | No autorizado | `rechazado`, con `codEstado` 3001 | Un comprobante en `PPR` todavía no está autorizado, así que espera a `AUT`. ## Otras tablas ### Tipo de emisión y ambiente No envíes `tipoEmision` ni `ambiente` en la Estructura del comprobante, porque la API responde 422. Usamos siempre la emisión normal (`tipoEmision` `1`) y el ambiente de la URL que llamas, como se explica en [Ambientes](/v1/guias/ambientes). Los dos códigos aparecen dentro de la clave de acceso; el del ambiente, en la posición 24: | Ambiente | URL base | Código SRI | |---|---|---| | Pruebas | `https://api-sandbox.mynexusapi.com` | `1` | | Producción | `https://api.mynexusapi.com` | `2` | ### Unidades de tiempo `pagos[].unidadTiempo` es texto libre de hasta 20 caracteres y es obligatoria cuando `plazo` es mayor que 0. Si la omites con `plazo` en 0, usamos `dias`. Los valores habituales son `dias`, `meses` y `anios`. ### Monedas `info.moneda` admite `DOLAR` o `USD`, y con cualquier otro valor la API responde 422. Si el campo es obligatorio o no depende del comprobante: | Comprobante | `moneda` | |---|---| | Factura, liquidación de compra, nota de crédito | Obligatoria | | Nota de débito | Opcional | | Guía de remisión, retención | No se envía (422) | ### Países (comercio exterior) `paisOrigen`, `paisDestino` y `paisAdquisicion`, en la factura de exportación, usan el código numérico de tres dígitos del catálogo de países del SRI. El de Ecuador es `593`. La tabla reproduce el catálogo de países del SRI. | Código | Descripción | |---|---| | 016 | AMERICAN SAMOA | | 074 | BOUVET ISLAND | | 101 | ARGENTINA | | 102 | BOLIVIA | | 103 | BRASIL | | 104 | CANADA | | 105 | COLOMBIA | | 106 | COSTA RICA | | 107 | CUBA | | 108 | CHILE | | 109 | ANGUILA | | 110 | ESTADOS UNIDOS | | 111 | GUATEMALA | | 112 | HAITI | | 113 | HONDURAS | | 114 | JAMAICA | | 115 | MALVINAS ISLAS | | 116 | MEXICO | | 117 | NICARAGUA | | 118 | PANAMA | | 119 | PARAGUAY | | 120 | PERU | | 121 | PUERTO RICO | | 122 | REPUBLICA DOMINICANA | | 123 | EL SALVADOR | | 124 | TRINIDAD Y TOBAGO | | 125 | URUGUAY | | 126 | VENEZUELA | | 127 | CURAZAO | | 129 | BAHAMAS | | 130 | BARBADOS | | 131 | GRANADA | | 132 | GUYANA | | 133 | SURINAM | | 134 | ANTIGUA Y BARBUDA | | 135 | BELICE | | 136 | DOMINICA | | 137 | SAN CRISTOBAL Y NEVIS | | 138 | SANTA LUCIA | | 139 | SAN VICENTE Y LAS GRANAD. | | 140 | ANTILLAS HOLANDESAS | | 141 | ARUBA | | 142 | BERMUDA | | 143 | GUADALUPE | | 144 | GUYANA FRANCESA | | 145 | ISLAS CAIMAN | | 146 | ISLAS VIRGENES (BRITANICAS) | | 147 | JOHNSTON ISLA | | 148 | MARTINICA | | 149 | MONTSERRAT ISLA | | 151 | TURCAS Y CAICOS ISLAS | | 152 | VIRGENES, ISLAS (NORT.AMER.) | | 201 | ALBANIA | | 202 | ALEMANIA | | 203 | AUSTRIA | | 204 | BELGICA | | 205 | BULGARIA | | 207 | ALBORAN Y PEREJIL | | 208 | DINAMARCA | | 209 | ESPANA | | 211 | FRANCIA | | 212 | FINLANDIA | | 213 | REINO UNIDO | | 214 | GRECIA | | 215 | PAISES BAJOS (HOLANDA) | | 216 | HUNGRIA | | 217 | IRLANDA | | 218 | ISLANDIA | | 219 | ITALIA | | 220 | LUXEMBURGO | | 221 | MALTA | | 222 | NORUEGA | | 223 | POLONIA | | 224 | PORTUGAL | | 225 | RUMANIA | | 226 | SUECIA | | 227 | SUIZA | | 228 | CANARIAS ISLAS | | 229 | UCRANIA | | 230 | RUSIA | | 231 | YUGOSLAVIA | | 233 | ANDORRA | | 234 | LIECHTENSTEIN | | 235 | MONACO | | 237 | SAN MARINO | | 238 | VATICANO (SANTA SEDE) | | 239 | GIBRALTAR | | 241 | BELARUS | | 242 | BOSNIA Y HERZEGOVINA | | 243 | CROACIA | | 244 | ESLOVENIA | | 245 | ESTONIA | | 246 | GEORGIA | | 247 | GROENLANDIA | | 248 | LETONIA | | 249 | LITUANIA | | 250 | MOLDOVA | | 251 | MACEDONIA | | 252 | ESLOVAQUIA | | 253 | ISLAS FAROE | | 260 | FRENCH SOUTHERN TERRITORIES | | 301 | AFGANISTAN | | 302 | ARABIA SAUDITA | | 303 | MYANMAR (BURMA) | | 304 | CAMBOYA | | 306 | COREA NORTE | | 307 | TAIWAN (CHINA) | | 308 | FILIPINAS | | 309 | INDIA | | 310 | INDONESIA | | 311 | IRAK | | 312 | IRAN (REPUBLICA ISLAMICA) | | 313 | ISRAEL | | 314 | JAPON | | 315 | JORDANIA | | 316 | KUWAIT | | 317 | LAOS, REP. POP. DEMOC. | | 318 | LIBANO | | 319 | MALASIA | | 321 | MONGOLIA (MANCHURIA) | | 322 | PAKISTAN | | 323 | SIRIA | | 325 | TAILANDIA | | 327 | BAHREIN | | 328 | BANGLADESH | | 329 | BUTAN | | 330 | COREA DEL SUR | | 331 | CHINA POPULAR | | 332 | CHIPRE | | 333 | EMIRATOS ARABES UNIDOS | | 334 | QATAR | | 335 | MALDIVAS | | 336 | NEPAL | | 337 | OMAN | | 338 | SINGAPUR | | 339 | SRI LANKA (CEILAN) | | 341 | VIETNAM | | 342 | YEMEN | | 343 | ISLAS HEARD Y MCDONALD | | 344 | BRUNEI DARUSSALAM | | 346 | TURQUIA | | 347 | AZERBAIJAN | | 348 | KAZAJSTAN | | 349 | KIRGUIZISTAN | | 350 | TAJIKISTAN | | 351 | TURKMENISTAN | | 352 | UZBEKISTAN | | 353 | PALESTINA | | 354 | HONG KONG | | 355 | MACAO | | 356 | ARMENIA | | 382 | MONTENEGRO | | 402 | BURKINA FASO | | 403 | ARGELIA | | 404 | BURUNDI | | 405 | CAMERUN | | 406 | CONGO | | 407 | ETIOPIA | | 408 | GAMBIA | | 409 | GUINEA | | 410 | LIBERIA | | 412 | MADAGASCAR | | 413 | MALAWI | | 414 | MALI | | 415 | MARRUECOS | | 416 | MAURITANIA | | 417 | NIGERIA | | 419 | ZIMBABWE (RHODESIA) | | 420 | SENEGAL | | 421 | SUDAN | | 422 | SUDAFRICA (CISKEI) | | 423 | SIERRA LEONA | | 425 | TANZANIA | | 426 | UGANDA | | 427 | ZAMBIA | | 429 | BENIN | | 430 | BOTSWANA | | 431 | REPUBLICA CENTROAFRICANA | | 432 | COSTA DE MARFIL | | 433 | CHAD | | 434 | EGIPTO | | 435 | GABON | | 436 | GHANA | | 437 | GUINEA-BISSAU | | 438 | GUINEA ECUATORIAL | | 439 | KENIA | | 440 | LESOTHO | | 441 | MAURICIO | | 442 | MOZAMBIQUE | | 443 | MAYOTTE | | 444 | NIGER | | 445 | RWANDA | | 446 | SEYCHELLES | | 447 | SAHARA OCCIDENTAL | | 448 | SOMALIA | | 449 | SANTO TOME Y PRINCIPE | | 450 | SWAZILANDIA | | 451 | TOGO | | 452 | TUNEZ | | 453 | ZAIRE | | 454 | ANGOLA | | 456 | CABO VERDE | | 458 | COMORAS | | 459 | DJIBOUTI | | 460 | NAMIBIA | | 463 | ERITREA | | 464 | MOROCCO | | 465 | REUNION | | 466 | SANTA ELENA | | 499 | JERSEY | | 501 | AUSTRALIA | | 503 | NUEVA ZELANDA | | 504 | SAMOA OCCIDENTAL | | 506 | FIJI | | 507 | PAPUA NUEVA GUINEA | | 508 | TONGA | | 509 | PALAO (BELAU) ISLAS | | 510 | KIRIBATI | | 511 | MARSHALL ISLAS | | 512 | MICRONESIA | | 513 | NAURU | | 514 | SALOMON ISLAS | | 515 | TUVALU | | 516 | VANUATU | | 517 | GUAM | | 518 | ISLAS COCOS (KEELING) | | 519 | ISLAS COOK | | 520 | ISLAS NAVIDAD | | 521 | MIDWAY ISLAS | | 522 | NIUE ISLA | | 523 | NORFOLK ISLA | | 524 | NUEVA CALEDONIA | | 525 | PITCAIRN, ISLA | | 526 | POLINESIA FRANCESA | | 529 | TIMOR DEL ESTE | | 530 | TOKELAI | | 531 | WAKE ISLA | | 532 | WALLIS Y FUTUNA, ISLAS | | 590 | SAINT BARTHELEMY | | 593 | ECUADOR | | 594 | AGUAS INTERNACIONALES | | 595 | ALTO VOLTA | | 596 | BIELORRUSIA | | 597 | COTE D'IVOIRE | | 598 | CYPRUS | | 599 | REPUBLICA CHECA | | 600 | FALKLAND ISLANDS | | 601 | LATVIA | | 602 | LIBIA | | 603 | NORTHERN MARIANA ISL | | 604 | ST. PIERRE AND MIQUE | | 605 | SYRIAN ARAB REPUBLIC | | 606 | TERRITORIO ANTARTICO BRITANICO | | 607 | TERRITORIO BRITANICO OCEANO IN | | 688 | SERBIA | | 831 | GUERNSEY | | 832 | JERSEY | | 833 | ISLE OF MAN | ## Siguientes pasos - [Factura](/v1/guias/emision-01): aplica los códigos de identificación, IVA y formas de pago en tu primer comprobante. - [Comprobante de retención](/v1/guias/emision-07): usa los códigos de retención y sustento con un ejemplo calculado. - [Glosario](/v1/guias/glosario): significado de los términos fiscales de esta página. --- # Estado del servicio Consulta sin API Key si la API está operativa, su disponibilidad de los últimos 90 días y los incidentes publicados, en JSON o en la página de estado. Cuando tu integración empieza a recibir errores `5xx` o tiempos de espera, lo primero que conviene saber es si el problema está en tu sistema o en el servicio. Para eso publicamos el estado de la API de forma abierta: no necesitas una API Key y puedes leerlo en la [página de estado](/v1/estado) o con una petición `GET /estado` desde tus propias alertas. Esta guía explica qué devuelve la consulta, cómo interpretar cada estado, con qué frecuencia puedes consultarla y qué hacer en tu integración cuando el servicio está degradado o caído. ## Endpoint ```text GET https://api.mynexusapi.com/estado ``` La ruta no lleva el prefijo `/v1`, no requiere la cabecera `X-Api-Key` y no recibe parámetros. ## Cuándo usarlo - Para mostrar el estado de la facturación en el panel de soporte de tu sistema. - Para decidir si pausas un proceso masivo cuando la API no está operativa y reanudarlo cuando vuelva a estarlo. - Para alimentar tus propias alertas sin gastar el [límite de solicitudes](/v1/guias/limite-de-request) de tu integración, porque esta consulta no usa tu API Key. Si quieres comprobar solamente que el servicio responde, `GET /salud` responde 200 con el estado `activo`. Para conocer el detalle de la disponibilidad y los incidentes, usa `GET /estado`. ## Ejemplo ```bash curl -s "https://api.mynexusapi.com/estado" ``` ```csharp using System.Net.Http; using var http = new HttpClient { BaseAddress = new Uri("https://api.mynexusapi.com") }; using HttpResponseMessage respuesta = await http.GetAsync("/estado"); Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}"); ``` ```javascript // Node.js 18 o superior. Guarda como estado.mjs y ejecuta: node estado.mjs const res = await fetch('https://api.mynexusapi.com/estado'); console.log(res.status, await res.text()); ``` ```php # Límites La API pone topes al tamaño del cuerpo, las cabeceras, el comprobante, las consultas, el ritmo de solicitudes y el cupo; aquí está cada valor y su error. Cada petición a la API tiene topes concretos: cuánto puede pesar el cuerpo, qué caracteres admite una cabecera, cuántas líneas lleva un comprobante o qué rango de fechas acepta una consulta. Aquí tienes todos esos valores en tablas, junto con la respuesta que recibes si superas cada uno. Los topes de tamaño, cabeceras, comprobante y consultas son los mismos en pruebas y en producción. Lo que cambia entre ambientes es el ritmo de solicitudes por minuto, que en un sandbox es menor, y el cupo, que se lleva por separado en cada ambiente. El límite de solicitudes por minuto tiene su propia página, [Límite de request](/v1/guias/limite-de-request), y aquí solo aparece resumido. ## Solicitud | Límite | Valor | Si lo superas | |---|---|---| | Tamaño del cuerpo en cualquier endpoint de emisión por tipo (por ejemplo, `POST /v1/contribuyentes/{identificacion}/facturas`) y en su validación (`POST .../{tipo}/validar`) | 2 MiB (2.097.152 bytes) | 413 con el `codEstado` 3006 (`cuerpo_excedido`). | | Tamaño del cuerpo en el resto de `POST` y `PUT` | 1 MiB (1.048.576 bytes) | 413 con el `codEstado` 3006 (`cuerpo_excedido`). | | Tamaño del archivo del logo en `POST /v1/contribuyentes/{identificacion}/perfil/logo` | 512 KB, en PNG o JPEG | 400 con el `codEstado` 3003 (`solicitud_invalida`), como se explica en [Perfil del emisor](/v1/guias/perfil-emisor). | | Profundidad del JSON (objetos y arreglos anidados) | 32 niveles | En la emisión y su validación, 422 con el `codEstado` 3002 (`comprobante_invalido`); en el resto, 400 con el `codEstado` 3003 (`solicitud_invalida`). | | `Content-Type` de la emisión | `application/json`, `application/xml` o `text/xml` | Un tipo distinto responde 415 con el `codEstado` 3003 (`solicitud_invalida`). | Un comprobante normal pesa unos pocos KB. Si te acercas a 2 MiB, revisa que no estés enviando datos repetidos o imágenes dentro de `infoAdicional`. ## Cabeceras | Cabecera | Regla | Si no la cumples | |---|---|---| | `X-Api-Key` | Es obligatoria en todo `/v1`. | 401 con el `codEstado` 3009 (`credenciales_invalidas`) si falta o es inválida; 403 con el `codEstado` 3010 (`ip_no_autorizada`) si la IP no está permitida. | | `Idempotency-Key` | Es obligatoria en la emisión. Tiene de 1 a 128 caracteres y solo admite letras ASCII sin tildes (`A-Z`, `a-z`), dígitos (`0-9`) y los símbolos `-` `_` `.` `:` `/`. | 400 con el `codEstado` 3003 (`solicitud_invalida`). | | `X-Api-Version` | Es opcional. Si la envías, debe ser la versión vigente, `2026-11-16`. | 400 con el `codEstado` 3007 (`version_no_soportada`). | | `X-Correlation-Id` | Es opcional. Si la envías con 1 a 64 caracteres `A-Z`, `a-z`, `0-9`, `.`, `_`, `-`, la API la usa y te la devuelve; si no cumple, la API genera una nueva. | No hay error. | | `X-Additional-Info` | Es opcional y sirve para identificar la solicitud al pedir soporte, por ejemplo `MiERP/4.2 sucursal=norte`. Va una sola vez por solicitud, solo con ASCII imprimible (0x20 a 0x7E) y como máximo 256 caracteres. No se guarda con el comprobante. No pongas datos personales ni secretos. | No hay error; si no cumple, no podremos usarla para ubicar tu solicitud. | Una `Idempotency-Key` se recuerda durante **7 días** dentro de tu integración y del ambiente. Cómo generarla y guardarla se explica en [Buenas prácticas](/v1/guias/buenas-practicas#idempotencia). ## Consultas Las consultas de listado y de búsqueda validan sus filtros antes de ejecutarse. Un valor fuera de rango responde 400 con el `codEstado` 3012 (`filtros_invalidos`), y el campo `errores` indica qué filtro corregir. | Consulta | Filtro | Regla | |---|---|---| | [`GET /v1/operaciones`](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente) | `desde` y `hasta` | Formato `yyyy-MM-dd`, desde el 2000-01-01. `hasta` no puede ser anterior a `desde` y entre ambas fechas puede haber como máximo 366 días. Sin fechas se usan los últimos 30 días. | | `GET /v1/operaciones` | `pagina` | De 1 a 10000. Por defecto, 1. | | `GET /v1/operaciones` | `tamanoPagina` | De 1 a 100. Por defecto, 20. | | `GET /v1/operaciones` | `buscar` | Hasta 100 caracteres, sin caracteres de control. | | `GET /v1/operaciones` | `tipoDocumento` | `01`, `03`, `04`, `05`, `06` o `07`. | | [`GET /v1/consultas/contribuyentes`](/v1/guias/consulta-contribuyente-nombre) | `max` | De 1 a 30. Por defecto, 10. | | `GET /v1/consultas/contribuyentes` | `apellidos` y `clase` | `apellidos` es obligatorio. `clase` admite `PersonaNatural` (por defecto), `Sociedad` o `SociedadPublica`. | | `GET /v1/catalogos/{nombre}` | `nombre` | Una clave que devuelva `GET /v1/catalogos`; otra responde 404 con el `codEstado` 3013 (`no_encontrado`). | ## Estructura del comprobante | Campo o colección | Regla | Si no la cumples | |---|---|---| | `origenReferencia` | Es obligatorio, con 1 a 64 caracteres del mismo juego que `Idempotency-Key`. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `referenciaExterna` | Es obligatorio, con 1 a 128 caracteres del mismo juego que `Idempotency-Key`. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `infoTributaria.ruc` | Solo admite dígitos, de 5 a 13. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `infoTributaria.estab` y `infoTributaria.ptoEmi` | Solo admiten dígitos, como máximo 3, y se completan con ceros a la izquierda. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `infoTributaria.secuencial` | Es opcional y solo admite dígitos, como máximo 9, de 1 a 999999999. Si lo omites o lo envías en ceros, asignamos el siguiente. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `detalles` | Lleva de 1 a 1000 líneas. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `detalles[].detallesAdicionales` | Admite hasta 3 por línea. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `info.pagos` | Lleva de 1 a 20 en la factura y en la liquidación de compra. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | `infoAdicional` | Admite hasta 15 objetos `{ "nombre", "valor" }`. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | | Campos desconocidos o repetidos | No se admiten. | 422 con el `codEstado` 3002 (`comprobante_invalido`). | Las reglas completas de cada tipo de comprobante están en [Comprobantes electrónicos](/v1/guias/emision) y en la guía de cada tipo. ## Tasa de peticiones | Límite | Valor | Si lo superas | |---|---|---| | Solicitudes por integración | 200 por minuto por defecto y 60 en un sandbox. | 429 con el `codEstado` 5005 (`limite_solicitudes`). | | Intentos de autenticación fallidos por IP | 20 por minuto. | 429 con el `codEstado` 5005 (`limite_solicitudes`). | | Consultas a `GET /estado` por IP, sin API Key | 60 por minuto. | 429 con el `codEstado` 5005 (`limite_solicitudes`). | El detalle, las cabeceras `X-RateLimit-*` y cómo esperar con `Retry-After` están en [Límite de request](/v1/guias/limite-de-request). ## Cupo El [cupo](/v1/guias/glosario#cupo) es la cantidad de comprobantes que puedes emitir en cada ambiente con tus paquetes pagados y vigentes. La emisión responde así según tu saldo: | Situación | Respuesta de la emisión | |---|---| | Te quedan documentos disponibles | 202 Accepted. | | No te quedan documentos | 429 con el `codEstado` 4004 (`cupo_agotado`). | | La solicitud tiene errores de forma (400, 409 o 413) | No consume cupo. | | El comprobante no pasa la validación (422) | Consume 1 documento como intento. Repetir la misma `Idempotency-Key` con el mismo cuerpo no consume otro. | Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo. Un comprobante `cancelado` no lo consume. Las consultas, las validaciones con `/validar`, las descargas y la gestión del perfil y de los webhooks tampoco consumen cupo. Antes de un lote grande, consulta tu saldo con [`GET /v1/consumo`](/v1/guias/consumo). ## Siguientes pasos - [Límite de request](/v1/guias/limite-de-request): cuántas solicitudes por minuto puedes hacer y cómo esperar. - [Errores](/v1/guias/errores): qué significa cada código y si se reintenta. - [Comprobantes electrónicos](/v1/guias/emision): reglas completas de la Estructura del comprobante. - [Consumo y cuotas](/v1/guias/consumo): consulta y amplía tu cupo. --- # Glosario Los términos de facturación electrónica en Ecuador y de la API, explicados para quien integra por primera vez. Si nunca antes trabajaste con facturación electrónica, encontrarás en la documentación palabras que vienen del SRI, como RUC, clave de acceso o RIDE, y otras propias de la API, como operación o `Idempotency-Key`. Este glosario explica cada una, agrupadas por tema, y al final indica qué término usar para cada concepto. Cada término tiene su propia ancla, así que puedes enlazarlo desde tu propia documentación con `/v1/guias/glosario#termino`, por ejemplo `/v1/guias/glosario#clave-de-acceso`. ## Fiscal: actores e identificación ### SRI El Servicio de Rentas Internas es la autoridad tributaria de Ecuador. Recibe los comprobantes electrónicos y los autoriza o los rechaza. No necesitas comunicarte con el SRI directamente, porque nosotros firmamos, transmitimos y consultamos por ti. Usa "SRI" solo para la autoridad, nunca para el comprobante ni para la API. ### Contribuyente Es la persona natural o la empresa registrada ante el SRI que emite o recibe comprobantes. En la API, un contribuyente es cada RUC habilitado para tu integración, y los ves en `GET /v1/contexto`. Una integración puede tener varios contribuyentes; el detalle está en [Contexto](/v1/guias/consulta-contexto). ### Emisor Es el contribuyente que emite el comprobante: el vendedor en una factura, el comprador en una liquidación de compra o el agente de retención en un comprobante de retención. Sus datos fiscales, como la razón social, la dirección matriz o si está obligado a llevar contabilidad, salen de su [perfil](/v1/guias/perfil-emisor) y no del cuerpo de la emisión. ### Receptor Es la otra parte del comprobante, también llamada contraparte: el comprador en una factura o nota, el proveedor en una liquidación de compra, el sujeto retenido en una retención o el destinatario en una guía de remisión. ### RUC El Registro Único de Contribuyentes es el número de 13 dígitos que identifica a un contribuyente ante el SRI. Su forma depende del tipo de contribuyente: | Tipo de contribuyente | Forma | Ejemplo de prueba | |---|---|---| | Persona natural | Los 10 dígitos de su cédula + `001` | `0123456789001` | | Sociedad privada | 13 dígitos; el tercero es `9` | - | | Entidad pública | 13 dígitos; el tercero es `6` | - | En la API, el RUC completo va en `infoTributaria.ruc` y también en la ruta, en `{identificacion}`. En pruebas usa solo los valores de [Datos de prueba](/v1/guias/datos-de-prueba) y nunca un RUC real. ### Cédula Es el documento de identidad de una persona en Ecuador y tiene 10 dígitos. Los dos primeros indican la provincia y el último es un dígito verificador. En un comprobante se usa para identificar al comprador o al proveedor que es persona natural, con `tipoIdentificacionComprador` en `05`. Puedes validar una cédula o un RUC con [Validar identificación](/v1/guias/consulta-identificacion). ### Identificación Es el valor que usas en las rutas de contribuyente de la API (`/v1/contribuyentes/{identificacion}/...`). Cópialo del campo `identificacion` de `GET /v1/contexto`; la API no acepta otra forma del mismo número. Es la identificación completa del contribuyente, tal como está registrada: para un RUC, sus 13 dígitos. El mismo valor va en `infoTributaria.ruc`. ## Fiscal: numeración del comprobante ### Establecimiento Es el local u oficina del contribuyente registrado en el SRI, ya sea la matriz o una sucursal. Se identifica con 3 dígitos, por ejemplo `001`, y en la API va en `infoTributaria.estab`. Puedes consultar los establecimientos de un RUC con [Establecimientos de un RUC](/v1/guias/consulta-establecimientos). ### Punto de emisión Es la caja, terminal o sistema que emite comprobantes dentro de un establecimiento. Se identifica con 3 dígitos, por ejemplo `001`, y en la API va en `infoTributaria.ptoEmi`. El establecimiento y el punto de emisión forman juntos la **serie**, por ejemplo 001-001. ### Secuencial Es el número consecutivo del comprobante dentro de su serie, de 9 dígitos, entre 000000001 y 999999999. Cada combinación de contribuyente, tipo de comprobante, establecimiento, punto de emisión y ambiente lleva su propia cuenta. El número completo del comprobante se escribe así: 001-001-000000123. En la API, `infoTributaria.secuencial` es **opcional**: | Envías | Resultado | |---|---| | Nada, o solo ceros (`"000000000"`) | Asignamos el siguiente de la serie (secuencial automático). | | Un número (`"123"` o `"000000123"`) | Se usa ese número, que solo admite dígitos y como máximo 9. | El secuencial automático continúa desde el mayor número que tenemos registrado para esa serie. Si vienes de otro sistema de facturación, envía el primer comprobante con el siguiente número de tu sistema anterior; después puedes dejar que nosotros numeremos. ### Clave de acceso Es el identificador único de 49 dígitos de cada comprobante electrónico, y en la API se llama `claveAcceso`. Nosotros la asignamos, así que **no** la envías en la solicitud; la obtienes en el [seguimiento](/v1/guias/consulta-operacion) o en el webhook, y con ella descargas el RIDE y el XML. La tabla muestra su estructura con una clave armada con datos de prueba, `0710202601012345678900110010010000001231234567811`: | Posiciones | Dígitos | Contenido | Ejemplo | |---|---|---|---| | 1 a 8 | 8 | Fecha de emisión `ddmmaaaa` | `07102026` | | 9 a 10 | 2 | Tipo de comprobante (`tipoDocumento`) | `01` | | 11 a 23 | 13 | RUC del emisor | `0123456789001` | | 24 | 1 | Ambiente: `1` pruebas, `2` producción | `1` | | 25 a 30 | 6 | Serie: establecimiento + punto de emisión | `001001` | | 31 a 39 | 9 | Secuencial | `000000123` | | 40 a 47 | 8 | Código numérico | `12345678` | | 48 | 1 | Tipo de emisión: `1` normal | `1` | | 49 | 1 | Dígito verificador (módulo 11) | `1` | Para leer las partes de una clave, usa [Decodificar clave de acceso](/v1/guias/consulta-clave-acceso). En la emisión offline del SRI, el número de autorización es la misma clave de acceso. ## Comprobantes ### Comprobante electrónico Es un documento tributario emitido en formato XML, firmado con el certificado digital del emisor y autorizado por el SRI. La API emite seis tipos, que se identifican por `tipoDocumento`: | `tipoDocumento` | Tipo | |---|---| | `01` | [Factura](#factura) | | `03` | [Liquidación de compra](#liquidacion-de-compra) | | `04` | [Nota de crédito](#nota-de-credito) | | `05` | [Nota de débito](#nota-de-debito) | | `06` | [Guía de remisión](#guia-de-remision) | | `07` | [Comprobante de retención](#retencion) | Usa "comprobante" para cualquiera de ellos y "factura" solo para el tipo `01`. ### Factura Es el comprobante `01`, que emite el vendedor al transferir bienes o prestar servicios. Detalla los productos, los impuestos y las formas de pago; la guía completa está en [Factura](/v1/guias/emision-01). ### Liquidación de compra Es el comprobante `03`, que emite el **comprador** cuando adquiere bienes o servicios a una persona que no puede emitir comprobantes de venta, por ejemplo una persona natural sin RUC o un proveedor del exterior. La guía completa está en [Liquidación de compra](/v1/guias/emision-03). ### Nota de crédito Es el comprobante `04`, que anula o reduce el valor de una factura ya autorizada por una devolución, un descuento posterior o una corrección a favor del comprador. Referencia el comprobante que modifica con `codDocModificado` y `numDocModificado`. La guía completa está en [Nota de crédito](/v1/guias/emision-04). ### Nota de débito Es el comprobante `05`, que aumenta el valor de un comprobante ya emitido por intereses de mora, gastos adicionales u otros cargos posteriores. La guía completa está en [Nota de débito](/v1/guias/emision-05). ### Guía de remisión Es el comprobante `06`, que respalda el traslado de mercadería con el punto de partida, el transportista, la placa, el destinatario y los productos. No lleva importes. La guía completa está en [Guía de remisión](/v1/guias/emision-06). ### Retención Es el comprobante `07`, que emite el **agente de retención**, normalmente el comprador, cuando retiene una parte del IVA o del impuesto a la renta que le debe a su proveedor (el sujeto retenido) y la paga directamente al SRI. Cada retención se apoya en un documento de [sustento](#sustento). La guía completa está en [Comprobante de retención](/v1/guias/emision-07). ### Sustento Es el documento que justifica otro comprobante. En una retención, el sustento es la factura del proveedor sobre la que retienes, que va en el bloque `docsSustento` con su número de 15 dígitos y su número de autorización de 49. El código de sustento tributario, `codSustento`, indica para qué se usa la compra. En una nota de crédito o de débito, el documento modificado cumple ese papel. ### RIDE La Representación Impresa del Documento Electrónico es el PDF del comprobante, con sus datos, la clave de acceso y la autorización. Sirve para entregarlo o imprimirlo, pero el documento con validez legal es el [XML autorizado](#xml-autorizado). Para obtenerlo, usa [Descargar PDF](/v1/guias/consulta-ride). ### XML autorizado Es el archivo XML del comprobante, firmado por el emisor y autorizado por el SRI. Es el documento con validez tributaria, así que guárdalo. Si lo descargas antes de que esté autorizado y disponible, la API responde 404 con el `codEstado` 3013 (`no_encontrado`). Para obtenerlo, usa [Descargar XML](/v1/guias/consulta-xml). ### Marca blanca Un contribuyente de marca blanca emite sus comprobantes y recibe la autorización del SRI como cualquier otro, pero no tiene RIDE ni correo del comprobante, así que la entrega al cliente final la haces desde tu sistema. Lo reconoces por el campo `marcaBlanca` en `true` de su fila en [`GET /v1/contexto`](/v1/guias/consulta-contexto). Para sus comprobantes, [Descargar PDF](/v1/guias/consulta-ride) responde 404 con el `codEstado` 3013 (`no_encontrado`), así que descarga el [XML autorizado](#xml-autorizado) y entrégalo desde tu sistema. La marca la configuramos nosotros por contribuyente. ### Autorización Es el resultado del SRI sobre un comprobante. En la API se lee en el campo `estado` de la operación: un comprobante tiene validez fiscal solo cuando su `estado` es `autorizado`. Los demás valores se explican en [Estado](#estado). ### Estado Es el campo `estado` de la operación, que también llega en los webhooks: | Valor | Significado | Qué hacer | |---|---|---| | `recibido` | Aceptamos el comprobante y aún no tiene resultado final. | Espera el webhook o consulta más tarde. | | `autorizado` | El SRI autorizó el comprobante. | Entrega el RIDE, porque el comprobante ya tiene validez fiscal. | | `rechazado` | No se autorizó por su contenido. | Corrígelo según `codEstado` y `errores` y emítelo de nuevo, como se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion#que-hacer-segun-el-estado). | | `rechazo_configuracion` | Falta o está mal una configuración del emisor. | Corrige la configuración y reenvía. | | `error` | No se pudo emitir por un fallo inesperado o definitivo. | Sigue la acción de su `codEstado`. | | `cancelado` | La plataforma canceló el envío; no se emitió. | Emite de nuevo con claves nuevas. | Junto al `estado` llega siempre el campo [`codEstado`](#codestado), que precisa el resultado. Cuando el `estado` es final y no es `autorizado`, `msgError` lo describe con un texto fijo y `errores` trae el detalle; el catálogo está en [Errores](/v1/guias/errores#codigos-de-resultado-de-una-operacion). ### codEstado Es el código numérico de 4 dígitos que acompaña al `estado` en la emisión, el seguimiento, los webhooks y todas las respuestas de error. Su primer dígito es el `estado`: 1 para `recibido`, 2 para `autorizado`, 3 para `rechazado`, 4 para `rechazo_configuracion`, 5 para `error` y 6 para `cancelado`. Por ejemplo, 1001 es un comprobante recibido, 2001 uno autorizado y 3002 uno que no cumple las validaciones. Programa tus decisiones con este número y no con el texto de `msgError`; el catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado). ### Recibido Es un comprobante que la API aceptó con un `202 Accepted` y que aún no tiene resultado final. No llames "recibido" a un comprobante autorizado ni "autorizado" a uno recibido. ## Impuestos y pagos ### IVA El Impuesto al Valor Agregado tiene el código de impuesto `2` en el campo `codigo`. La tarifa general vigente es del 15%, y también existen tarifas del 0%, del 5% y otras, cada una con su `codigoPorcentaje`. Todos los códigos están en [Catálogos](/v1/guias/catalogos). ### ICE El Impuesto a los Consumos Especiales grava bienes como bebidas alcohólicas, cigarrillos o vehículos, y tiene el código de impuesto `3`. La API admite el ICE porcentual. Cuando aplica, el IVA se calcula sobre la base más el ICE. ### IRBPNR El Impuesto Redimible a las Botellas Plásticas No Retornables tiene el código de impuesto `5`. La API **no** lo admite, y un comprobante que lo incluya recibe un 422. ### Tarifa Es el porcentaje del impuesto, expresado como número (15 para el 15%). En los impuestos del comprobante va en `tarifa` y debe corresponder al `codigoPorcentaje`. ### codigoPorcentaje Es el código del SRI que identifica la tarifa de un impuesto. Para el IVA, los valores son estos: | `codigoPorcentaje` | Tarifa | |---|---| | `0` | 0% | | `2` | 12% | | `3` | 14% | | `4` | 15% (general vigente) | | `5` | 5% | | `6` | No objeto de impuesto | | `7` | Exento de IVA | | `8` | IVA diferenciado | | `10` | 13% | ### Base imponible Es el valor sobre el que se calcula un impuesto: la cantidad por el precio unitario, menos el descuento, y más el ICE cuando se trata del IVA. En la API va en `baseImponible`. ### Forma de pago Indica cómo se pagó o se pagará el comprobante, con un código del SRI en `formaPago`. Por ejemplo, `01` es sin utilización del sistema financiero, `19` es tarjeta de crédito y `20` es otros con utilización del sistema financiero. La factura y la liquidación de compra requieren al menos una, y la lista completa está en [Catálogos](/v1/guias/catalogos). ## API: acceso y cuenta ### API Key Es la credencial de tu integración. Se envía en la cabecera `X-Api-Key` de cada petición, cubre todos tus contribuyentes habilitados y, en producción, solo funciona desde las IP registradas. El detalle está en [Autenticación](/v1/guias/autenticacion). ### Ambiente Es el entorno en el que trabajas, de pruebas o de producción, y cada uno tiene su URL: `https://api-sandbox.mynexusapi.com` para pruebas, sin validez fiscal, y `https://api.mynexusapi.com` para producción. Las diferencias están en [Ambientes y contribuyentes](/v1/guias/ambientes). ### Sandbox Es tu espacio de pruebas por autoservicio, que creas en `https://portal.mynexusapi.com/sandbox`. Incluye una API Key de pruebas, un usuario del Portal del Cliente y un cupo de pruebas de 3.000 documentos sin vencimiento, y solo existe en el ambiente de pruebas. Desde el mismo portal pasas a producción cuando terminas de probar. Cómo crearlo se explica en [Sandbox de pruebas](/v1/guias/sandbox). ### Paquete Es una cantidad de documentos para emitir en un ambiente, con su vigencia. Los de producción duran un año desde el pago; el de pruebas no vence. El saldo de un paquete vencido se pierde. ### Cupo Son los documentos que te quedan para emitir en el ambiente: la suma de tus paquetes pagados y vigentes. Cada comprobante que el SRI autoriza o rechaza consume un documento, y lo mismo ocurre si la operación termina rechazada por su contenido o por la configuración del emisor, si la emisión responde 422 por validación o si reenvías un comprobante rechazado con otro contenido. Si la operación queda `cancelado`, no consume cupo. Sin cupo, la emisión responde 429 con el `codEstado` 4004 (`cupo_agotado`); el detalle está en [Consumo y cuotas](/v1/guias/consumo). ## API: emisión y seguimiento ### Operación Es el proceso de emisión de un comprobante, desde que lo recibimos hasta que el SRI responde. Se identifica con `idOperacion`, un UUID que recibes en el 202 de la emisión. No la llames transacción ni ticket. ### Seguimiento Es la consulta del estado de una operación después de emitir, con `GET /v1/operaciones/{idOperacion}`, o su recepción por webhook. El detalle está en [Seguimiento de una operación](/v1/guias/consulta-operacion). ### Idempotency-Key Es la cabecera obligatoria de la emisión que identifica tu intención de emitir un comprobante. Admite de 1 a 128 caracteres ASCII (letras, dígitos y `-` `_` `.` `:` `/`) y se recuerda 7 días por integración y ambiente. Cómo usarla se explica en [Buenas prácticas](/v1/guias/buenas-practicas#idempotencia). ### Idempotencia Es la propiedad de una operación que puedes repetir sin cambiar el resultado. En la emisión significa que, si reenvías el mismo cuerpo con la misma `Idempotency-Key`, la API devuelve un 202 con el mismo `idOperacion` y el estado actual de la operación, en lugar de crear otro comprobante. ### X-Correlation-Id Es la cabecera que la API devuelve en toda respuesta con el identificador de esa petición, con el que podemos ubicarla. Guárdalo y envíanoslo cuando nos reportes un problema. Si mandas tu propio `X-Correlation-Id` válido, la API lo reutiliza; el detalle está en [Respuestas del API](/v1/guias/respuestas). ### X-Additional-Info Es una cabecera opcional con un texto tuyo, por ejemplo `MiERP/4.2 sucursal=norte`, con el que podemos encontrar tu solicitud cuando nos pides soporte. No se guarda con el comprobante ni se devuelve en la respuesta. Solo admite ASCII imprimible, como máximo 256 caracteres, y no debe llevar datos personales ni secretos; las reglas están en [Límites](/v1/guias/limites#cabeceras). ### Referencia externa Es el identificador del documento en tu sistema, formado por `referenciaExterna` (hasta 128 caracteres) y `origenReferencia` (hasta 64). También evita duplicados: la misma referencia con el mismo cuerpo devuelve la operación original, y con otro cuerpo, o si ya pertenece a otro comprobante, la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Para emitir de nuevo un comprobante rechazado o no emitido, usa una referencia nueva. ## API: notificaciones ### Webhook Es una petición HTTP `POST` que te enviamos a una URL HTTPS pública tuya cuando una operación termina, para que no tengas que consultar. Lo configuras en el Portal del Cliente, en **Integración > Eventos**, y el detalle está en [Webhooks](/v1/guias/webhooks). ### Destino (webhook) Es la URL de tu servidor que recibe los webhooks, registrada con su secreto en **Integración > Eventos**. Debe usar `https://` en el puerto 443, resolver a una IP pública y responder sin redirecciones en menos de 15 segundos. Si no responde, o responde con un 408, un 429 o un 5xx, reintentamos la entrega varias veces, como se explica en [Webhooks](/v1/guias/webhooks#reintentos-y-que-se-considera-fallo). Un 3xx u otro 4xx deja la entrega rechazada por tu servidor, sin reintentos. Tras 8 fallos consecutivos el destino se pausa, y los eventos que ocurren mientras está pausado no se le entregan ni quedan en espera. ### Evento Es el tipo de aviso que entrega un webhook, en el campo `eventType`: | `eventType` | Significado | |---|---| | `document.authorized` | El SRI autorizó el comprobante. | | `document.rejected` | El SRI rechazó el comprobante. | | `document.failed` | El comprobante no se emitió; `estado` y `codEstado` dicen por qué. | | `operation.requires_attention` | Aviso de que todavía no tenemos el resultado de un comprobante, que sigue `recibido`; con `probe` en `"true"`, es el evento de prueba del botón **Probar** del portal. | ### HMAC El Hash-based Message Authentication Code es una firma calculada con una clave secreta compartida. Cada webhook trae la cabecera `Ecuafact-Signature: t=,v1=`, donde la firma es el HMAC-SHA256 de `t + "." + cuerpo crudo` con el secreto de tu webhook. Recalcúlala en tu servidor y compárala para saber que el aviso lo enviamos nosotros; el procedimiento está en [Verificación de firma](/v1/guias/webhooks-firma). ## Términos fijos Usa siempre el mismo término para el mismo concepto: **comprobante**, **emisión**, **operación**, **seguimiento**, **autorización**, **claveAcceso**, **RIDE**, **contribuyente**, **ambiente** y **API Key**. ## No llames X a Y | No uses | Usa | Por qué | |---|---|---| | "recibido" como sinónimo de autorizado | "recibido" (aún sin resultado) y "autorizado" (resultado del SRI) | Un comprobante recibido **no** está autorizado. | | "factura" para cualquier comprobante | "comprobante" o el tipo (factura, nota de crédito, retención...) | Hay seis tipos con reglas propias. | | "SRI" para el comprobante o para la API | "el SRI" solo para la autoridad | Así no se confunden la autoridad y el documento. | | "credenciales" (plural) para varios RUC | "una API Key por integración" | Una API Key cubre todos sus RUC habilitados. | | "estado fiscal" genérico | `estado` (resultado de la operación) y `codEstado` (código que lo precisa) | El estado dice qué pasó y el código dice por qué. | | "token" o "clave secreta" | "API Key" | La credencial tiene un solo nombre. | | "transacción" o "ticket" | "operación" (`idOperacion`) | El proceso de emisión tiene un solo nombre. | ## Siguientes pasos - [Primeros pasos](/v1/guias/primeros-pasos): aplica estos términos emitiendo tu primer comprobante. - [Comprobantes electrónicos](/v1/guias/emision): los campos de cada tipo de comprobante. - [Catálogos](/v1/guias/catalogos): todos los códigos del SRI (impuestos, formas de pago, identificaciones). - [Preguntas frecuentes](/v1/guias/faq): respuestas a las dudas más comunes al integrar. --- # Preguntas frecuentes Respuestas a las dudas más comunes al integrar la API, desde un 401 inesperado hasta el paso a producción. Aquí respondemos las preguntas que más se repiten durante una integración: por qué una API Key correcta responde 401, si un 202 significa que el comprobante está autorizado, cómo continuar la numeración de otro sistema o qué hacer cuando el SRI rechaza un comprobante. Cada respuesta es breve y enlaza a la guía donde está el detalle. Si tu duda no aparece aquí, puedes buscar el código que recibiste en [Errores](/v1/guias/errores) o el término que no conoces en el [Glosario](/v1/guias/glosario). ## Acceso ### ¿Por qué mi API Key responde 401 o 403 si la copié bien? En producción, la API también valida la IP de origen; el sandbox acepta cualquier IP. Si la API Key es correcta pero tu servidor sale a Internet por una IP que no está en **Cuenta > IP permitidas**, la respuesta es un 403 con el `codEstado` 3010 (`ip_no_autorizada`). Si la API Key está ausente, es inválida o fue revocada, la respuesta es un 401 con el `codEstado` 3009 (`credenciales_invalidas`). Revisa estos puntos en orden: 1. Comprueba que la cabecera se llame exactamente `X-Api-Key` y que el valor sea la API Key completa, con el punto en medio. 2. Comprueba en el Portal del Cliente, en **Cuenta > API Keys**, que la API Key no esté revocada. 3. Comprueba que la IP pública de tu servidor esté registrada. Para averiguarla, ejecuta `curl -4 https://ifconfig.me` desde ese mismo servidor. 4. Si tu servidor tiene IPv6, ten en cuenta que la conexión puede salir por IPv6; registra también esa IP o fuerza IPv4. El detalle está en [Autenticación](/v1/guias/autenticacion#registra-tu-ip). ### Mi IP cambia (nube, oficina, casa). ¿Qué hago? La API solo acepta IP exactas, IPv4 o IPv6, o rangos IPv4 en notación CIDR como 203.0.113.0/24. Si tu IP cambia, la solución depende de dónde corre tu código: - En la nube, asigna una IP pública estática a la máquina o configura una salida fija (un NAT gateway) y registra esa IP. - En una oficina con varias IP de un mismo proveedor, registra el rango CIDR que te asignó el proveedor. - En desarrollo desde casa, vuelve a registrar tu IP cuando cambie. No registres rangos amplios "por si acaso", porque cada IP permitida es un punto de entrada más para tu API Key. ### ¿Puedo llamar a la API desde el navegador o desde una app móvil? No. La API Key daría acceso a emitir comprobantes a cualquiera que abra las herramientas del navegador o descompile la app. Además, la API no habilita CORS, así que el navegador bloquea la respuesta, y solo acepta las IP registradas, mientras que cada usuario final tiene la suya. Llama a la API desde tu backend y haz que tu frontend hable con tu backend. ### Recibo 429 aunque hago pocas peticiones. ¿Por qué? Un 429 puede tener dos causas distintas, y el `codEstado` del cuerpo te dice cuál es: | `codEstado` | Causa | Qué hacer | |---|---|---| | 5005 (`limite_solicitudes`) | Tu IP acumuló 20 autenticaciones fallidas en el minuto, por ejemplo por un proceso que reintenta con una API Key equivocada, o superaste las solicitudes por minuto de tu integración. | Corrige la API Key o la IP y espera los segundos que indica `Retry-After`. | | 4004 (`cupo_agotado`) | Se agotó tu cupo de documentos. | Amplía tu cupo, porque esperar no lo repone. | El detalle está en [Límite de request](/v1/guias/limite-de-request). ## Emisión ### La emisión respondió 202: ¿el comprobante ya está autorizado? No. `202 Accepted` significa que **recibimos** el comprobante, y la autorización del SRI llega después. Espera el [webhook](/v1/guias/webhooks) o consulta `GET /v1/operaciones/{idOperacion}` hasta que su `estado` deje de ser `recibido`. El recorrido completo está en [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida). ### ¿Qué responde la API si reenvío la misma emisión? Responde con la misma operación: un 202 con `estado` en `recibido` y el mismo `idOperacion`, sin crear otro comprobante. Eso ocurre cuando repites la misma `Idempotency-Key` con el mismo cuerpo, o la misma `referenciaExterna` con el mismo cuerpo. El resultado actual de esa operación lo ves en el [seguimiento](/v1/guias/consulta-operacion). Si esa operación terminó en `cancelado`, el reenvío te devuelve la misma operación y **no** emite. Para emitir, envía una `Idempotency-Key` y una `referenciaExterna` nuevas. ### ¿Tengo que enviar la clave de acceso o el secuencial? La [clave de acceso](/v1/guias/glosario#clave-de-acceso) no, porque nosotros la asignamos y ese campo no existe en la solicitud; si lo envías, la API responde 422. El [secuencial](/v1/guias/glosario#secuencial) es opcional: si lo omites o lo envías en ceros, asignamos el siguiente de la serie, y si envías un número, se usa ese. La clave de acceso la recibes en el seguimiento o en el webhook, y el número asignado lo ves en sus dígitos 31 a 39 o en `numeroDocumento` del seguimiento. ### Ya facturaba con otro sistema. ¿Cómo continúo la numeración? Envía el primer comprobante de cada serie (establecimiento, punto de emisión y tipo) con el siguiente secuencial de tu sistema anterior, por ejemplo `"1251"` si el último fue el 1250. Desde ahí puedes omitir el secuencial, porque continuamos desde el mayor número registrado en esa serie. ### Mi servidor se cayó justo después de enviar. ¿Se emitió o no? No lo sabes hasta preguntar, y para eso existe la `Idempotency-Key`. Reenvía el **mismo cuerpo** con la **misma** `Idempotency-Key`: - Si la primera petición llegó, recibes un 202 con el `idOperacion` original, y no se duplica nada. - Si no llegó, recibes un 202 con un `idOperacion` nuevo, que es la emisión que no se había hecho. Para que esto funcione, guarda la `Idempotency-Key` y la `referenciaExterna` en tu base de datos **antes** de enviar. La clave se recuerda 7 días; el detalle está en [Buenas prácticas](/v1/guias/buenas-practicas#idempotencia). ### ¿Por qué recibo 409? Un 409 indica un conflicto con algo que ya existe, y el `codEstado` te dice cuál: | `codEstado` | Causa | Qué hacer | |---|---|---| | 3004 (`comprobante_duplicado`) | Ya existe un comprobante con ese número (`estab` + `ptoEmi` + `secuencial`) en proceso, autorizado o rechazado por el SRI. | No lo reenvíes. Si querías otro comprobante, usa otro secuencial u omítelo. | | 3005 (`conflicto_idempotencia`) | Reutilizaste una `Idempotency-Key`, o una `referenciaExterna`, con un cuerpo distinto, o la `referenciaExterna` ya pertenece a otro comprobante. | Si es un reintento, envía el cuerpo original sin cambios. Si es otra emisión, usa una clave y una referencia nuevas. | El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ### Recibo 422. ¿Cómo sé qué campo está mal? Lee el arreglo `errores` del cuerpo: en un 422 de comprobante trae hasta 20 problemas, cada uno con la ruta del campo cuando aplica, por ejemplo `$.infoTributaria.ruc: Campo obligatorio.` Corrige todos los que puedas y vuelve a enviar; los que no se hayan podido validar aparecerán en la siguiente respuesta. Un 422 de validación consume 1 documento como intento, pero no usa un número de la serie, así que puedes corregir y reenviar con la misma `Idempotency-Key`. Las reglas de cada comprobante están en [Comprobantes electrónicos](/v1/guias/emision). ### ¿Puedo enviar el comprobante en XML? Sí. Puedes enviar el XML del SRI con `Content-Type: application/xml` o `text/xml` en los seis endpoints de emisión y en sus validaciones. La API aplica las mismas reglas que al JSON y la firma que traiga el XML se ignora. También puedes seguir enviando JSON. El detalle está en [Cuerpo JSON o XML](/v1/guias/emision#cuerpo-json-o-xml). ## Después de emitir ### ¿Cuánto tarda la autorización del SRI? No hay un tiempo garantizado, porque depende del SRI. Nosotros obtenemos el resultado por ti y te avisamos por webhook cuando lo tenemos. Mientras tanto, la operación se mantiene con `estado` en `recibido`, que no es un resultado final. Si la operación termina en `error` con el `codEstado` 5007 (`resultado_no_confirmado`), no pudimos confirmar si el comprobante llegó a crearse; escribe a soporte con el `idOperacion`. Mientras la operación esté en `recibido`, y también en ese caso, no reenvíes el comprobante con otra `Idempotency-Key`, porque podrías duplicarlo; con el secuencial automático, además, recibiría un número nuevo. ### ¿Qué hago si el SRI rechaza mi comprobante? Sabes que el SRI lo rechazó porque la operación tiene `estado` en `rechazado` y `codEstado` en 3001 (`rechazo_sri`), o porque recibes el evento `document.rejected`. El campo `errores` trae el mensaje del SRI. El comprobante rechazado no tiene validez fiscal, así que corrígelo con estos pasos: 1. Revisa los datos del comprobante contra la guía de su tipo: los totales, los impuestos, la identificación del receptor y el documento de sustento. 2. Corrige el cuerpo. 3. Envíalo como un comprobante nuevo, con un secuencial **nuevo** (u omítelo para que asignemos el siguiente) y con una `Idempotency-Key` y una `referenciaExterna` **nuevas**. Si reutilizas el número rechazado por el SRI, la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`). Si en cambio el comprobante no llegó a emitirse, porque la operación terminó en `rechazado` con 3002 (`comprobante_invalido`), en `rechazo_configuracion` o en `error` con 5006 (`entrega_no_posible`), corrige la causa que indican `codEstado` y `errores` y reenvíalo con el **mismo** número. Para eso, envía el mismo `estab`, `ptoEmi` y `secuencial`, con una `Idempotency-Key` y una `referenciaExterna` nuevas. La API reutiliza la misma operación, responde 202 con el mismo `idOperacion` y no descuenta otro documento. Confirma después el resultado con el seguimiento, como se explica en [Webhooks](/v1/guias/webhooks#que-hacer-ante-cada-evento). Si no identificas la causa, pide soporte con el `idOperacion` y el `X-Correlation-Id`, como se explica en [Cómo pedir soporte](/v1/guias/errores#como-pedir-soporte). ### ¿Puedo anular una factura autorizada? La API no tiene una operación de anulación. Para revertir total o parcialmente una factura autorizada, emite una [nota de crédito](/v1/guias/emision-04) que la referencie. La anulación formal de un comprobante ante el SRI se gestiona fuera de la API, con los procedimientos del SRI. ### ¿Cómo obtengo el PDF (RIDE) y el XML? Cuando el comprobante esté autorizado, usa su `claveAcceso` con estas guías: - Para el RIDE, el PDF del comprobante, usa [Descargar PDF](/v1/guias/consulta-ride). - Para el XML, usa [Descargar XML](/v1/guias/consulta-xml). Mientras falta la autorización o el archivo, recibes HTTP `404`, `codEstado` 3013 (`no_encontrado`); reintenta la descarga. - El envío por correo lo haces desde tu sistema, con el RIDE o el XML descargado. ### ¿Por qué el RIDE responde 404 si el comprobante está autorizado? Es lo que ocurre con un contribuyente de [marca blanca](/v1/guias/glosario#marca-blanca), que tiene `marcaBlanca` en `true` en [`GET /v1/contexto`](/v1/guias/consulta-contexto). Sus comprobantes se emiten y se autorizan igual que los demás, pero no tienen RIDE, así que [Descargar PDF](/v1/guias/consulta-ride) responde siempre 404 con el `codEstado` 3013 (`no_encontrado`). El [XML](/v1/guias/consulta-xml) se descarga igual. No reintentes esas dos llamadas, porque la respuesta no va a cambiar. Descarga el [XML autorizado](/v1/guias/consulta-xml) y entrégalo a tu cliente desde tu sistema; si necesitas una representación impresa, genérala a partir de ese XML. Revisa `marcaBlanca` antes de pedir el RIDE o el correo para evitar las dos llamadas. ### ¿Un comprobante rechazado consume cupo? Sí. Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo, y uno cancelado no consume. Las solicitudes que rechaza la propia API (400, 403, 409 o 429) no consumen nada, un 422 de validación consume 1 documento como intento, y reenviar corregido el mismo número de un comprobante que no llegó a emitirse no descuenta un documento adicional. El detalle está en [Consumo y cuotas](/v1/guias/consumo). ## Webhooks ### ¿Cómo pruebo los webhooks en mi computadora? La URL del webhook debe usar `https://`, estar en el puerto 443 y resolver a una IP pública, así que `localhost` y las IP privadas se rechazan. Para recibir los webhooks en tu computadora, sigue estos pasos: 1. Levanta tu receptor local, por ejemplo en `http://localhost:3000/webhooks/ecuafact`. 2. Exponlo con un túnel HTTPS público, por ejemplo con `ngrok http 3000` o `cloudflared tunnel --url http://localhost:3000`. 3. Registra la URL pública del túnel (por ejemplo `https://abc123.ngrok-free.app/webhooks/ecuafact`) en el Portal del Cliente, en **Integración > Eventos**, y guarda el secreto. 4. Pulsa **Probar**. Te enviamos un evento de prueba firmado, con `eventType` en `operation.requires_attention` y `probe` en `true`. Verifica la firma y responde con un 2xx. 5. Emite un comprobante en pruebas y espera `document.authorized` o `document.rejected`. La URL de un destino no se edita, así que cada vez que el túnel cambie de URL, crea un **Nuevo destino** con la URL nueva y deshabilita el anterior. Tu receptor debe responder en menos de 15 segundos. Si quieres probar la verificación de la firma sin túnel, usa la prueba local de entrega firmada de [Webhooks](/v1/guias/webhooks). ### ¿Cómo verifico que un webhook lo enviamos nosotros? Con la firma de la cabecera `Ecuafact-Signature: t=,v1=`. Calcula el HMAC-SHA256 de `t + "." + cuerpo crudo` con tu secreto y compáralo con `v1`, usando el cuerpo tal como llegó, sin volver a serializarlo. El procedimiento completo está en [Verificación de firma](/v1/guias/webhooks-firma). ## Pruebas y producción ### ¿Los comprobantes de pruebas tienen validez fiscal? No. Todo lo que emites en `https://api-sandbox.mynexusapi.com` va al ambiente de pruebas del SRI y no tiene validez fiscal. Usa solo los [Datos de prueba](/v1/guias/datos-de-prueba). ### ¿Necesito un certificado digital? Sí. El SRI exige que cada comprobante vaya firmado con el certificado digital del emisor, un archivo `.p12` o `.pfx`. Al crear el [sandbox](/v1/guias/sandbox) cargas el certificado y su contraseña, y desde ahí firmamos por ti, así que tu código nunca maneja el certificado. ### ¿Cómo paso a producción? El paso a producción tiene cinco pasos: 1. Completa en pruebas tu flujo de emisión, reintentos, webhook y descarga del RIDE, con la lista de [Buenas prácticas](/v1/guias/buenas-practicas#checklist-antes-de-produccion). 2. Entra al Portal del Cliente y usa **Pasar a producción** cuando se cumplan las condiciones (correo verificado, firma vigente y 5 comprobantes aceptados). Al confirmar, tu cuenta recibe 20 documentos de producción por un año. 3. Guarda la API Key de producción en tu gestor de secretos y registra las IP de salida de tu servidor de producción. 4. Cambia la URL base a `https://api.mynexusapi.com`. 5. Verifica con `GET /v1/contexto` que ves tus contribuyentes y emite un primer comprobante real. La lista de verificación completa está en [Ambientes y contribuyentes](/v1/guias/ambientes). ### ¿Qué pasa cuando vence mi sandbox? El sandbox no vence: recibes 3.000 documentos una sola vez, sin renovación automática. El saldo no se repone al cambiar de mes ni al repetir el alta; si necesitas más, abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/) y un administrador agrega la ampliación. Para emitir con validez fiscal, completa **Pasar a producción** en el portal. El detalle está en [Sandbox de pruebas](/v1/guias/sandbox#vencimiento). ## Otros ### ¿Hay SDK oficiales? Sí, puedes integrarte con nuestros SDK oficiales para .NET, Node.js, Python, Java y PHP. Manejan por ti la API Key y la `Idempotency-Key`, y reintentan con la misma clave los cortes de red y los estados 408, 425, 500, 502, 503 y 504, hasta 3 intentos y respetando `Retry-After`. El SDK reintenta por defecto el 429 con el `codEstado` 5005 (`limite_solicitudes`); el 429 con el `codEstado` 4004 (`cupo_agotado`) no se reintenta nunca. El detalle está en [SDKs](/v1/guias/sdk). ### ¿Cómo pido soporte? Abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/) con el `X-Correlation-Id` de la respuesta, la URL, el estado HTTP, el `codEstado` y el cuerpo que enviaste, sin la API Key. También puedes consultar el [centro de ayuda](https://ecuafact.com/ayuda/) o escribir por [WhatsApp](https://wa.me/593988315544). La lista completa está en [Cómo pedir soporte](/v1/guias/errores#como-pedir-soporte). ### ¿Cómo encuentra soporte mi solicitud? La encontramos por el `X-Correlation-Id` que devuelve cada respuesta. Si no lo guardaste, podemos buscarla por el texto que enviaste en la cabecera opcional `X-Additional-Info` (por ejemplo `MiERP/4.2 sucursal=norte lote=42`). Te recomendamos enviar las dos cabeceras desde el inicio, sin datos personales ni secretos, como se explica en [Identifica tus solicitudes](/v1/guias/buenas-practicas#identifica-tus-solicitudes). ## Siguientes pasos - [Primeros pasos](/v1/guias/primeros-pasos): emite tu primer comprobante en pruebas. - [Errores](/v1/guias/errores): todos los códigos y qué hacer ante cada uno. - [Buenas prácticas](/v1/guias/buenas-practicas): idempotencia y reintentos con código listo para copiar. - [Glosario](/v1/guias/glosario): los términos fiscales y de la API explicados. --- # Versionado El contrato de la API se identifica por una versión con fecha; aquí ves cuál está vigente, qué cambios son compatibles y cómo se anuncia un retiro. La versión mayor de la API es la V1 y forma parte de la ruta (`/v1`). Dentro de ella, cada versión del contrato se identifica con una fecha que te devolvemos en la cabecera `X-Api-Version`. Lo habitual son los cambios compatibles; si alguna vez hiciera falta un cambio incompatible, lo marcaríamos como **incompatible** en el [Changelog](/v1/guias/changelog), con su fecha y lo que debes hacer. Aquí ves cómo versionamos el contrato, qué cambios puedes esperar y cómo preparar tu código para tolerarlos. Te recomendamos consultarla cuando diseñes cómo tu integración lee las respuestas o si recibes un 400 con el `codEstado` 3007 (`version_no_soportada`). Al terminar sabrás si debes enviar `X-Api-Version`, qué cambios no te afectan y cómo te enterarías de un retiro. ## Conceptos - **Versión mayor (`/v1`).** Forma parte de la ruta. Un cambio que rompa a los integradores existentes se publicaría en una ruta nueva o, de forma excepcional, dentro de `/v1`, anunciado como incompatible en el Changelog. - **Versión del contrato (fecha).** Dentro de `/v1`, el contrato se identifica con una fecha `aaaa-mm-dd`. La vigente es `2026-11-16`, y la API la devuelve en la cabecera `X-Api-Version` de cada respuesta. - **Cambio compatible.** Es un cambio que no rompe a un integrador que ignora lo que no conoce, por ejemplo un campo nuevo en una respuesta. ## Versión vigente | Versión | Fecha del contrato | Estado | Retiro | |---|---|---|---| | V1 | 2026-11-16 | Actual | Sin fecha de retiro | Una forma rápida de comprobar la versión es llamar a `GET /v1/contexto` con la cabecera `X-Api-Version: 2000-01-01`, que no corresponde a ninguna versión. La API responde 400 antes de autenticar, así que no gastas cupo ni necesitas tu API Key, y el cuerpo trae `codEstado` con el número 3007: ```json { "estado": "rechazado", "codEstado": 3007, "msgError": "Versión de API no admitida.", "errores": [] } ``` El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado). ### Calendario en formato de máquina El calendario en formato de máquina está en [api-versions.json](/.well-known/api-versions.json). Para cada versión incluye `version`, `status`, `releaseDate`, `deprecationDate`, `sunsetDate`, `reference` (la referencia de la API) y `changelog`, y en la raíz indica la versión actual en `current`. El detalle de cada cambio está en el [Changelog](/v1/guias/changelog). ## Cabecera `X-Api-Version` La cabecera funciona en los dos sentidos, aunque en la solicitud es opcional: | Uso | Obligatoria | Valor | |---|---|---| | Solicitud | No | La fecha de la versión que quieres usar, por ejemplo `2026-11-16`. Si no la envías, responde la versión vigente. | | Respuesta | Siempre en `/v1` | La versión del contrato que respondió. | | Envías | Resultado | |---|---| | Sin `X-Api-Version` | Responde la versión vigente. Es lo recomendado. | | `X-Api-Version: 2026-11-16` | Responde la versión vigente. | | Cualquier otro valor, por ejemplo `2025-01-01` | La API responde 400 con el `codEstado` 3007, antes de autenticar. | Te recomendamos no enviar la cabecera en tus solicitudes y registrar en tus logs el valor de `X-Api-Version` de las respuestas. Así detectas cuándo cambia la versión sin que tu integración falle. > [!NOTE] > Si fijas `X-Api-Version` en tu código, cuando esa versión se retire todas tus > peticiones responderán 400 con el `codEstado` 3007. Fíjala solo si tienes previsto > cómo actualizarla. ## Qué cambios son compatibles Lo habitual dentro de `/v1` son cambios **compatibles**. Te recomendamos preparar tu integración para tolerarlos: | Cambio compatible (se registra en el Changelog) | Qué debe hacer tu código | |---|---| | Un campo nuevo en una respuesta JSON | Ignora los campos que no conoce. No uses deserializadores que fallen ante campos desconocidos. | | Un endpoint nuevo | No necesita hacer nada. | | Un código de error nuevo del catálogo | Trata un `codEstado` desconocido según su primer dígito, que fija el `estado`, y según el estado HTTP: corrige ante un 4xx y reintenta ante un 5xx. | | Un `eventType` de webhook nuevo | Responde con un 2xx e ignóralo sin detener el procesamiento. | | Un valor nuevo en un enumerado, por ejemplo un estado | Trátalo como desconocido sin romper el flujo. | | Un campo opcional nuevo en la solicitud | No necesita hacer nada, porque si no lo envías el comportamiento no cambia. | Estos otros cambios son incompatibles. Los publicaríamos en una versión nueva o, de forma excepcional, dentro de `/v1`. En los dos casos los marcaríamos como **incompatibles** en el [Changelog](/v1/guias/changelog), con la fecha, el impacto y qué hacer. | Cambio incompatible | |---| | Quitar o renombrar un campo de la solicitud o de la respuesta | | Volver obligatorio un campo opcional | | Cambiar el tipo o el formato de un campo | | Cambiar el significado de un código de error o de un estado | Ten en cuenta que en las solicitudes la regla es la contraria: la API **rechaza** los campos desconocidos en la Estructura del comprobante con un 422 y el `codEstado` 3002. Por eso no envíes campos que no estén documentados en la guía de su tipo de comprobante. ## Deprecación y retiro Cuando una versión se reemplace, te avisaremos del retiro con tiempo y en varios lugares: 1. Lo anunciamos en el [Changelog](/v1/guias/changelog) y en esta página, con la fecha de deprecación y la fecha de retiro. 2. `api-versions.json` publica `deprecationDate` y `sunsetDate`. 3. Las respuestas de esa versión incluyen las cabeceras de deprecación del RFC 8594: `Deprecation`, que indica desde cuándo está obsoleta, y `Sunset`, que indica cuándo dejará de responder. 4. La versión sigue operativa durante el periodo de solapamiento. Al llegar la fecha de retiro, responde 400 con el `codEstado` 3007. Mientras una versión no esté en deprecación, sus respuestas no traen las cabeceras `Deprecation` ni `Sunset`. La V1 no lo está. ## Reglas de la V1 que debes conocer Si conoces otras APIs de facturación del SRI, estas reglas de la Estructura del comprobante son las que más errores evitan: | Regla | Qué hacer | |---|---| | `version` y `formato` no van en la Estructura del comprobante | Si los envías, la API responde 422 con el `codEstado` 3002. | | `ambiente` y `tipoEmision` no se envían, ni en la raíz ni en `infoTributaria` | El ambiente lo define la URL y la emisión es siempre normal; si los envías, la API responde 422 con el `codEstado` 3002. | | `infoTributaria.claveAcceso` no se envía | Deja que nosotros asignemos la clave de acceso; la obtienes en la respuesta 202 cuando el `codEstado` es 1002, en el seguimiento o en el webhook. | | `infoTributaria.secuencial` es opcional | Omítelo o envíalo en ceros para que asignemos el siguiente. | | El tipo de comprobante lo fija la ruta de emisión | Usa la ruta del tipo que emites: `facturas`, `liquidaciones-compra`, `notas-credito`, `notas-debito`, `guias-remision` o `retenciones`. No envíes `infoTributaria.tipoDocumento` en el cuerpo; `tipoDocumento` se lee en las respuestas y se usa en los filtros de consulta. | | Los datos propios del tipo de comprobante van en `info` | Arma `info` solo con los campos de ese tipo. | | Las respuestas JSON traen sus campos en el primer nivel | Lee cada campo directamente en la raíz del JSON, sin buscar una clave contenedora. | | El resultado de una emisión está en `estado` | Sigue la operación mientras `estado` sea `recibido`, con `codEstado` 1001 o 1002; con cualquier otro valor ya es final, y `codEstado`, `msgError` y `errores` explican la causa cuando no es `autorizado`. | | Los errores son planos (`estado`, `codEstado`, `msgError`, `errores`) y `codEstado` es un número estable de cuatro dígitos, como 3002 | Decide con `codEstado` y el estado HTTP, y lee el identificador de la petición en la cabecera `X-Correlation-Id`, porque no viene en el cuerpo. | ## Siguientes pasos - [Changelog](/v1/guias/changelog): los cambios de la API con su fecha, impacto y qué hacer. - [Respuestas del API](/v1/guias/respuestas): cabeceras de respuesta, incluida `X-Api-Version`. - [Errores](/v1/guias/errores#catalogo-de-codestado): el `codEstado` 3007 y el resto del catálogo. ---