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

Prompt para agentes

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 codEstado 3010 (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_attempts es menor que 1.
  • Un tiempo (timeout, connect_timeout, total_timeout) no es mayor que 0.
  • max_response_bytes no es un entero mayor que 0, 0 ni None.
  • Una espera (retry_*_ms, max_retry_delay_ms) es negativa.
  • additional_info no cumple su formato.
  • Combinas http_client o transport con proxy o verify.

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 en resultado.idempotency_key o, si falla, en error.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, lanza EcuafactSdkException sin llamar a la API.
  • get_operacion, consultar_operacion y esperar_resultado exigen un UUID; si no lo es, lanzan EcuafactSdkException sin 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:

  • EmisionResultado trae admission, idempotency_key y correlation_id (cabecera X-Correlation-Id). admission es una Operation, con los campos que se describen en Seguimiento del resultado. En una emisión aceptada, estado es recibido y cod_estado es 1001 o 1002: con 1001, clave_acceso todavía es None, y con 1002 ya trae la clave de acceso. Tu código debe aceptar los dos valores. url_estado es la URL completa del seguimiento.
  • ArchivoComprobante tiene contenido (bytes) y content_type. Si el comprobante no está autorizado, la API devuelve HTTP 404, como se explica en Descargar XML.
  • Los métodos de consultas SRI y para lanzan EcuafactSdkException sin 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#

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.