En esta página
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.
Importante
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:
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 |
| 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. - 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
codEstado3010 (ip_no_autorizada).
Instalación#
Usa un entorno virtual para no mezclar dependencias.
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.
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 de tu API Key.
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. |
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. |
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). 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. |
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. |
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_attemptses menor que 1.- Un tiempo (
timeout,connect_timeout,total_timeout) no es mayor que 0. max_response_bytesno es un entero mayor que 0,0niNone.- Una espera (
retry_*_ms,max_retry_delay_ms) es negativa. additional_infono cumple su formato.- Combinas
http_clientotransportconproxyoverify.
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, emite una factura, espera el resultado del SRI con el seguimiento y descarga el RIDE, 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 de la serie estab-ptoEmi. El
script reemplaza ruc por el de tu contexto y fechaEmision por la fecha de
hoy.
{
"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.
estab y ptoEmi deben ser un establecimiento y un
punto de emisión de tu emisor; el sandbox crea el
establecimiento 001 con el punto de emisión 001. Cada campo está explicado en Factura. Si
prefieres armar el comprobante con métodos en lugar de JSON, usa los
constructores.
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. Así tu proceso no se queda esperando.
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#
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 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. |
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. 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. |
Nota
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.
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 devuelven directamente el modelo de su tipo.
El filtro tipo_documento de listar_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) con /validar al final, como se detalla en
Métodos. 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:
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.
# 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.
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 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 | 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.
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, 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#
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 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.
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.
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.
construir_evento verifica la cabecera Ecuafact-Signature
(t=<epoch>,v1=<hmac>) 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.
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.
# 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 (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,<base64>). 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.
evento = construir_evento_webhook(SECRETOS, request.headers, request.get_data())
Atención
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, y el algoritmo de la firma, en Verificación de 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. |
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). 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. 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. |
Atributo de EcuafactApiException |
Tipo | Descripción |
|---|---|---|
cod_estado |
int \| None |
Código numérico del catálogo 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.
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, 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. |
| 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 enresultado.idempotency_keyo, si falla, enerror.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, lanzaEcuafactSdkExceptionsin llamar a la API. get_operacion,consultar_operacionyesperar_resultadoexigen un UUID; si no lo es, lanzanEcuafactSdkExceptionsin llamar a la API.
Atención
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. |
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.
# 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.
| 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.
# 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.
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.
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 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 o
validar_antes_de_emitir. Todo valor que
asignes se envía tal cual.
# 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 <idOperacion> 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.
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.
| 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.
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.
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); 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 |
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. |
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) |
get_salud() |
GET /salud |
Salud (status y cuerpo), como se explica en 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. |
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. |
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 |
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) |
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) |
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:
EmisionResultadotraeadmission,idempotency_keyycorrelation_id(cabeceraX-Correlation-Id).admissiones unaOperation, con los campos que se describen en Seguimiento del resultado. En una emisión aceptada,estadoesrecibidoycod_estadoes 1001 o 1002: con 1001,clave_accesotodavía esNone, y con 1002 ya trae la clave de acceso. Tu código debe aceptar los dos valores.url_estadoes la URL completa del seguimiento.ArchivoComprobantetienecontenido(bytes) ycontent_type. Si el comprobante no está autorizado, la API devuelve HTTP404, como se explica en Descargar XML.- Los métodos de consultas SRI y
paralanzanEcuafactSdkExceptionsin 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.
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.
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.
Contexto y consumo#
Antes de emitir puedes preguntar con qué contribuyentes puedes trabajar y
cuántos documentos te quedan. get_contexto() lee el
contexto de tu API Key y get_consumo() lee tu
cupo. Ninguna de las dos consume cupo.
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.
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.
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.
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, Contribuyentes por nombre, Establecimientos de un RUC, Validar identificación y Decodificar clave de 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 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 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.
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.
Estado del servicio#
get_estado_servicio() devuelve un EstadoServicio. Tiene los mismos campos
que la respuesta de la consulta, 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.
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().
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. 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: revisa todos los campos y las reglas de cálculo para construir tus comprobantes.
- Seguimiento de una operación: consulta qué significa cada
estadoy cadacodEstado. - Webhooks: recibe el resultado del SRI sin consultar en bucle.
- Visión general de los SDK: compara los cinco SDK y decide entre SDK o HTTP directo.