Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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 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.
  • 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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.