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

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#

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.