En esta página
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.
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 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 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.
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.
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 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. 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 |
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 |
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.
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.
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.
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.
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.
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. La guía completa
está en Comprobante de retención.
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. Para obtenerlo, usa Descargar PDF.
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.
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. Para sus comprobantes,
Descargar PDF responde 404 con el codEstado 3013 (no_encontrado), así que descarga el
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#
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. |
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, 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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. 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=<epoch>,v1=<firma>, 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.
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: aplica estos términos emitiendo tu primer comprobante.
- Comprobantes electrónicos: los campos de cada tipo de comprobante.
- Catálogos: todos los códigos del SRI (impuestos, formas de pago, identificaciones).
- Preguntas frecuentes: respuestas a las dudas más comunes al integrar.