En esta página
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.
- 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 ejemplo001-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
estadode 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 unidOperacion. El resultado del SRI lo conoces después, consultando la operación o recibiendo un webhook. Detalle en Ciclo de vida del comprobante. - 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.
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 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.
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. Detalle en
Autenticación.
Tipos de comprobante#
tipoDocumento |
Comprobante | Cuándo se emite | Guía |
|---|---|---|---|
01 |
Factura | Vendes un bien o servicio. | Factura |
03 |
Liquidación de compra | Compras a una persona que no puede emitirte factura. | Liquidación de compra |
04 |
Nota de crédito | Anulas o reduces el valor de una factura (devolución, descuento posterior). | Nota de crédito |
05 |
Nota de débito | Aumentas el valor de una factura (intereses, recargos). | Nota de débito |
06 |
Guía de remisión | Trasladas mercadería. | Guía de remisión |
07 |
Comprobante de retención | Retienes impuestos al pagar a un proveedor. | Comprobante de retención |
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 |
POST |
/v1/contribuyentes/{identificacion}/facturas |
Emitir una factura. | Factura |
POST |
/v1/contribuyentes/{identificacion}/liquidaciones-compra |
Emitir una liquidación de compra. | Liquidación de compra |
POST |
/v1/contribuyentes/{identificacion}/notas-credito |
Emitir una nota de crédito. | Nota de crédito |
POST |
/v1/contribuyentes/{identificacion}/notas-debito |
Emitir una nota de débito. | Nota de débito |
POST |
/v1/contribuyentes/{identificacion}/guias-remision |
Emitir una guía de remisión. | Guía de remisión |
POST |
/v1/contribuyentes/{identificacion}/retenciones |
Emitir un comprobante de retención. | Comprobante de retención |
POST |
/v1/contribuyentes/{identificacion}/facturas/validar |
Validar sin emitir; usa la misma ruta del tipo seguida de /validar. |
Validar sin emitir |
GET |
/v1/operaciones/{idOperacion} |
Seguir una emisión hasta su autorización. | Seguimiento de una operación |
GET |
/v1/operaciones |
Listar las operaciones de un contribuyente por fecha. | Listado de operaciones |
GET |
/v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride |
Descargar el RIDE (PDF). | Descargar PDF |
GET |
/v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml |
Descargar el XML. | Descargar XML |
GET |
/v1/contribuyentes/{identificacion}/perfil |
Ver el perfil del emisor (datos que salen en el RIDE). | Perfil del emisor |
PUT |
/v1/contribuyentes/{identificacion}/perfil |
Actualizar el perfil del emisor. | Perfil del emisor |
POST |
/v1/contribuyentes/{identificacion}/perfil/logo |
Cambiar el logo del RIDE. | Perfil del emisor |
GET |
/v1/consumo |
Ver tu cupo de documentos. | Consumo y cuotas |
GET |
/v1/catalogos y /v1/catalogos/{nombre} |
Consultar los códigos del SRI (impuestos, formas de pago y otros). | Catálogos |
GET |
/estado |
Ver el estado del servicio, sin API Key. | Estado del servicio |
GET |
/v1/consultas/contribuyentes/{identificacion} |
Consultar un contribuyente en el SRI. | Contribuyente por identificación |
GET |
/v1/consultas/contribuyentes |
Buscar contribuyentes por nombre. | Contribuyentes por nombre |
GET |
/v1/consultas/establecimientos/{ruc} |
Listar los establecimientos de un RUC. | Establecimientos de un RUC |
GET |
/v1/consultas/identificacion/validar/{numero} |
Validar una cédula o RUC. | Validar identificación |
GET |
/v1/consultas/comprobantes/decodificar/{claveAcceso} |
Decodificar una clave de acceso. | Decodificar clave de acceso |
El cuerpo de los seis tipos comparte la misma estructura, que describe
Comprobantes electrónicos. 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.
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 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. 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, 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 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 desde tu terminal o desde tus scripts. Y si prefieres explorar la API antes de escribir código, importa nuestra colección de Postman.
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 (arriba) y Ciclo de vida | Primeros pasos |
| Desarrollador que quiere emitir hoy | Sandbox de pruebas | Primeros pasos |
| Integrador con un SDK | SDKs | Comprobantes electrónicos |
| Quien quiere emitir desde la terminal, scripts o archivos de su ERP | CLI de Ecuafact | Emitir desde CSV o Excel |
| Quien prepara el paso a producción | Datos de prueba (casos) | Ambientes y contribuyentes |
| Quien busca un campo, límite o código | Errores, Límites, Catálogos | Referencia API |
| Quien integra un agente de IA | MCPs | Agentes |
Siguientes pasos#
- Sandbox de pruebas: consigue tu API Key de pruebas en unos 10 minutos.
- Primeros pasos: emite tu primera factura y descarga su RIDE.
- Ciclo de vida del comprobante: qué pasa entre el envío y la autorización.
- Referencia API: la especificación OpenAPI interactiva.