Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

ecuafact (Python)

Cliente oficial en Python del API publico de facturacion electronica Ecuafact (contrato v1). Cubre autenticacion, idempotencia, reintentos configurables, importes exactos (Decimal), espera del resultado, logo del perfil y webhooks tipados. Requiere Python 3.10+. Incluye py.typed.

Versión preliminar actual: 1.0.0b7.

Instalacion

pip install "ecuafact>=1.0.0b7"

Uso

from decimal import Decimal
from ecuafact import ComprobanteRequest, EcuafactClient, EcuafactClientOptions, InfoDocumento, InfoTributaria

# Sin opciones, el cliente lee ECUAFACT_BASE_URL y ECUAFACT_API_KEY.
client = EcuafactClient(EcuafactClientOptions(
    base_address="https://staging-api.mynexusapi.com/",  # sandbox; produccion: https://api.mynexusapi.com/
    identificacion="0123456789001",  # identificacion completa de GET /v1/contexto (RUC de 13 digitos); opcional
))

resultado = client.emitir(ComprobanteRequest(
    origen_referencia="MiERP",
    referencia_externa="FACTURA-2026-0001",
    info_tributaria=InfoTributaria(ruc="0123456789001", tipo_documento="01", estab="002", pto_emi="001"),
    info=InfoDocumento(total_sin_impuestos=Decimal("10.00"), importe_total=Decimal("11.50")),
    # detalles=..., pagos=...
))
# 202: "recibido" con cod_estado 1001 (sin clave de acceso) o 1002 (con clave_acceso)
print(resultado.admission.estado, resultado.admission.cod_estado, resultado.admission.id_operacion)

operacion = client.esperar_resultado(resultado.admission.id_operacion, intervalo=5, maximo=120)
if operacion.es_autorizado:
    print("Autorizado", operacion.clave_acceso)
elif operacion.es_final:
    print(operacion.estado, operacion.cod_estado, operacion.msg_error, operacion.errores)  # p. ej. rechazado / 3001
else:
    print("Aun recibido; consulta de nuevo mas tarde")

La respuesta 202 de la emision y la operacion (GET /v1/operaciones/{id}) tienen los mismos campos (Admission es el mismo tipo que Operation): estado, cod_estado, msg_error, errores, id_operacion, url_estado (URL absoluta del seguimiento), ambiente, tipo_documento, numero_documento, referencia_externa, clave_acceso, fh_recibido y fh_autorizacion. La operacion sigue en recibido (cod_estado 1001 sin clave de acceso o 1002 con clave_acceso) hasta llegar a un estado final: autorizado (2001), rechazado (3xxx: el contenido del comprobante no paso la validacion fiscal o del SRI), rechazo_configuracion (4xxx: falta o esta mal una configuracion del emisor), error (5xxx) o cancelado (6001). cod_estado es un numero de 4 digitos cuyo primer digito es el estado. Si no es autorizado, msg_error trae la descripcion general del codigo y errores, el detalle especifico (por ejemplo, el mensaje del SRI).

identificacion en las rutas es siempre el valor identificacion de GET /v1/contexto: la identificacion completa, por ejemplo el RUC 0123456789001. El comprobante no lleva secuencial: la plataforma lo asigna.

Multi-RUC

ruc = client.para("0123456789001")
ruc.validar(comprobante)                          # valida sin emitir
resultado = ruc.emitir(comprobante)
ruc.esperar_resultado(resultado.admission.id_operacion)
ruc.descargar_ride(clave_acceso)
ruc.descargar_xml(clave_acceso)
ruc.get_perfil()
ruc.actualizar_perfil(PerfilEmisorUpdate(telefono="0999999999"))
ruc.actualizar_logo(open("logo.png", "rb").read(), "image/png", "logo.png")

Importes

Los importes, cantidades, precios y tarifas son decimal.Decimal. Puedes pasar int, float, Decimal o str ("12.50"); el SDK los envia como numero JSON exacto (12.50, no "12.50"). Un float se toma con 15 cifras significativas, asi que 0.1 + 0.2 se envia como 0.3. Los importes de las respuestas se leen como Decimal sin perder precision.

Idempotencia

idempotency_key es opcional: si no se envia, el SDK la genera, la reutiliza en los reintentos y la devuelve en resultado.idempotency_key (y en el error, como idempotency_key). Al reintentar a nivel de aplicacion reutiliza la clave devuelta. Solo admite letras, digitos y - _ . : /, maximo 128 caracteres; una clave invalida falla antes de enviar. La correlacion queda en resultado.correlation_id (o correlation_id en el error).

Reintentos

Se reintentan las solicitudes idempotentes (GET, emision con Idempotency-Key, logo) ante fallos de conexion y los estados de retry_status_codes (por defecto 408, 425, 500, 502, 503, 504).

  • 429 con cod_estado 5005 (limite_solicitudes): se reintenta por defecto, respetando Retry-After con el tope max_retry_delay_ms. retry_rate_limited=False lo desactiva.
  • Cualquier otro 429, como el 4004 (cupo_agotado) o uno sin cuerpo, nunca se reintenta.
  • actualizar_perfil no se reintenta.

Opciones

Opcion Default Descripcion
base_address ECUAFACT_BASE_URL URL absoluta http/https del despliegue, sin /v1
api_key ECUAFACT_API_KEY Credencial X-Api-Key; no admite espacios al inicio/fin ni caracteres de control; nunca aparece en repr
identificacion None Contribuyente por defecto (valor de GET /v1/contexto)
timeout 30.0 Tiempo maximo de cada intento, incluida la lectura del cuerpo (segundos) o httpx.Timeout
connect_timeout None Tiempo maximo para conectar (segundos); None = timeout
total_timeout None Tope de toda la llamada, incluidos reintentos (segundos)
user_agent Ecuafact.Sdk/1.0 User-Agent (se envia en cada solicitud)
additional_info None Se envia como X-Additional-Info en cada solicitud; ASCII imprimible, sin espacios al inicio/fin, maximo 256; None o vacio no la envia; nunca aparece en repr
retry_transient_failures True False desactiva todos los reintentos
max_attempts 3 Intentos por solicitud (minimo 1)
retry_status_codes 408, 425, 500, 502, 503, 504 Estados HTTP reintentables
retry_rate_limited True Reintenta el 429 con cod_estado 5005 (limite_solicitudes); ningun otro 429
retry_backoff "linear" "linear" (base x intento) o "exponential" (base x 2^(intento-1))
retry_base_delay_ms 200 Espera base entre reintentos
retry_jitter_ms 50 Variacion aleatoria maxima de la espera
respect_retry_after True Respeta Retry-After
max_retry_delay_ms 60000 Espera maxima entre reintentos (0 = sin tope)
http_client None httpx.Client propio (proxy, TLS, pool); el SDK no lo cierra
proxy None Proxy del cliente interno ("http://proxy:3128")
verify None TLS del cliente interno: True/False, ruta a bundle CA o ssl.SSLContext
transport None Transporte httpx propio (por ejemplo httpx.MockTransport en pruebas)

Una opcion invalida lanza EcuafactConfigurationException al crear el cliente.

Opciones por llamada

Cada metodo que llama al API acepta opciones=RequestOptions(...) como ultimo argumento (keyword). Solo afecta a esa llamada; el resto usa la configuracion del cliente.

Campo Default Descripcion
timeout None (usa options.timeout) Tiempo maximo de cada intento (segundos o httpx.Timeout)
total_timeout None (usa options.total_timeout) Tope de toda la llamada, incluidos reintentos y esperas (segundos)
correlation_id None Se envia como X-Correlation-Id: de 1 a 64 caracteres A-Z a-z 0-9 . _ -
additional_info None (usa options.additional_info) Se envia como X-Additional-Info solo en esta llamada; None usa el del cliente y "" no la envia en esta llamada
reintentos True False desactiva los reintentos solo en esa llamada
from ecuafact import RequestOptions

opciones = RequestOptions(timeout=10, total_timeout=30, correlation_id="pedido-457", reintentos=True)
resultado = client.emitir(comprobante, "FACTURA-2026-0001", opciones=opciones)
print(resultado.correlation_id)  # pedido-457 (el que devuelve el API)

operacion = client.get_operacion(resultado.admission.id_operacion, opciones=RequestOptions(reintentos=False))
ruc = client.para("0123456789001")
ruc.descargar_ride(clave_acceso, opciones=RequestOptions(timeout=60))
  • Un correlation_id o un tiempo invalido lanza EcuafactConfigurationException al crear RequestOptions.
  • La correlacion queda en resultado.correlation_id y en correlation_id de cualquier excepcion del SDK (tambien en EcuafactTimeoutException y EcuafactConnectionException). Si el API no devuelve X-Correlation-Id, se expone el que enviaste.
  • reintentos=True no reactiva reintentos que el cliente desactivo (retry_transient_failures=False), ni reintenta solicitudes no idempotentes (actualizar_perfil).
  • En esperar_resultado, las opciones se aplican a cada consulta.
  • El SDK Python no tiene cancelacion: acota la llamada con timeout y total_timeout.

Constructores de comprobantes

Opcionales. Arman el mismo ComprobanteRequest para factura (01), liquidacion de compra (03), nota de credito (04), nota de debito (05), guia de remision (06) y retencion (07).

from ecuafact import ComprobanteBuilder, Iva, calcular_totales, validar_comprobante

factura = (
    ComprobanteBuilder.factura("0123456789001", "002", "001")
    .referencias("MiERP", "FACTURA-2026-0001")
    .fecha_emision("07/10/2026")
    .comprador("05", "0123456789", "CONTRIBUYENTE DE PRUEBAS", "DIRECCION DE PRUEBAS")
    .linea("SERV-001", "CONSULTORIA", 3, "12.50", "2.50", Iva.TARIFA_15)
    .linea("REP-002", "REPUESTO", 3, "1.0112", 0, Iva.TARIFA_15)
    .linea("LIB-003", "LIBRO", 2, "4.35", 0, Iva.TARIFA_0)
    .moneda("DOLAR")
    .pago("01", "20.00")
    .pago("19")                 # sin total: recibe lo que falta (32.44)
    .calcular_totales()
)
errores = factura.validar()     # [] si todo cuadra
client.emitir(factura.construir(), "FACTURA-2026-0001")
  • Tus valores mandan. Todo importe que asignes (en linea(...), detalle(Detalle(...)), info(importe_total=...), pago(forma, total), un Impuesto con valor) se respeta. calcular_totales() solo rellena lo vacio (None).
  • Calculo (reglas del API): subtotal de linea round(cantidad x precio - descuento, 2); IVA sobre la base sin redondear mas el ICE de la linea; cabecera totalConImpuestos por codigo + codigoPorcentaje (IVA primero, luego ICE, en orden de aparicion) sumando las lineas; importeTotal = subtotal + IVA + ICE + propina; descuento vacio = 0; propina 0 en factura; moneda DOLAR en 01, 03 y 04 si falta; un pago sin total recibe lo que falta. Nota de debito: IVA = suma del IVA redondeado de cada motivo. Retencion: valorImpuesto, totalSinImpuestos (suma de bases), importeTotal, valorRetenido y el pago; pagoLocExt 01 por defecto.
  • Precision: Precision(importes=2, cantidades=6, redondeo="HALF_UP"). Modos: HALF_UP, HALF_DOWN, HALF_EVEN, UP, DOWN, CEILING, FLOOR (o la constante de decimal). Pasa la tuya como ComprobanteBuilder.factura(ruc, estab, pto_emi, precision=Precision(...)). Otra precision puede producir importes que el API rechaza con 422.
  • validar() devuelve una lista de Inconsistencia(campo, mensaje, esperado, actual) (str(i) da "info.importeTotal: no coincide con ... (esperado 52.44, actual 52.45)"); no lanza ni bloquea emitir.
  • Sin constructor: calcular_totales(request, precision=None) devuelve una copia con los importes vacios calculados y validar_comprobante(request, precision=None) devuelve las inconsistencias; el tipo sale de infoTributaria.tipoDocumento.
  • Tarifas: Iva.TARIFA_0, Iva.TARIFA_5, Iva.TARIFA_8, Iva.TARIFA_15 (codigo 4), Iva.NO_OBJETO, Iva.EXENTO, Tarifa("4", 15) o la tupla ("4", 15). ICE: linea(..., ice=("3011", 10)). Las tarifas de IVA y las tablas de impuestos son las vigentes del SRI y el SDK las fija como constantes; no las consulta al API.
Tipo Metodos propios
factura comprador, linea, detalle, propina, moneda, pago
liquidacion_compra proveedor, linea, detalle, moneda, pago
nota_credito comprador, documento_modificado, motivo, linea (codigoInterno), detalle, moneda
nota_debito comprador, documento_modificado, motivo(razon, valor), iva, moneda, pago
guia_remision transportista, traslado, destinatario, linea(codigo, descripcion, cantidad)
retencion sujeto_retenido, periodo_fiscal, parte_relacionada, documento_sustento, impuesto_sustento, retencion, pago

Comunes: referencias, secuencial, fecha_emision, info(**campos), info_adicional, calcular_totales, validar, construir.

Errores

Excepcion Cuando Que hacer
EcuafactConnectionException Sin conexion o respuesta cortada Reintenta con la misma Idempotency-Key
EcuafactTimeoutException Tiempo del intento o total_timeout agotado Reintenta con la misma Idempotency-Key o consulta la operacion
EcuafactConfigurationException Opciones invalidas Corrige la configuracion
EcuafactWebhookException Firma (motivo firma_invalida) o cuerpo (motivo cuerpo_invalido) de webhook invalidos Responde 401 o 400 segun motivo
EcuafactAuthException 401 / 403 Revisa la API Key, el alcance o el plan
EcuafactValidationException 400 / 422 Corrige el comprobante segun errores
EcuafactNotFoundException 404 Revisa el identificador
EcuafactConflictException 409 Duplicado o clave reutilizada con otro contenido
EcuafactRateLimitException 429 con 5005 (limite_solicitudes) Espera retry_after
EcuafactQuotaException 429 con 4004 (cupo_agotado) Cupo agotado: no reintentes
EcuafactServerException 5xx Reintenta mas tarde con la misma clave

Todas heredan de EcuafactSdkException; las del API, de EcuafactApiException. Todos los errores del API llegan con la misma forma, { estado, codEstado, msgError, errores }, y la excepcion expone cod_estado (int, por ejemplo 3002), msg_error (descripcion general del codigo), errores (detalle especifico, siempre una lista), estado, status (codigo HTTP; estado_http queda como alias), correlation_id, idempotency_key, retry_after (timedelta o None) y es_reintentable. Toda EcuafactSdkException tiene correlation_id (correlacion de la llamada, o None).

Compara cod_estado con las constantes de CodEstado en lugar de usar numeros sueltos:

from ecuafact import CodEstado, EcuafactApiException

try:
    client.emitir(comprobante)
except EcuafactApiException as error:
    if error.cod_estado == CodEstado.COMPROBANTE_INVALIDO:
        print(error.msg_error, error.errores)  # 3002: la descripcion general y cada problema con su ruta

estado_de_cod_estado(codigo) deduce el estado a partir del primer digito, util ante un codigo nuevo que el SDK aun no tenga como constante. EstadosPublicos trae los valores de texto de estado.

Webhooks

from ecuafact import TipoEventoWebhook, construir_evento, EcuafactWebhookException

try:
    evento = construir_evento([secreto_actual, secreto_anterior], cabecera, await request.body())
except EcuafactWebhookException as error:
    return Response(status_code=401 if error.es_firma_invalida else 400)
if evento.event_type is TipoEventoWebhook.DOCUMENTO_AUTORIZADO:
    marcar_autorizado(evento.id_operacion, evento.clave_acceso)
elif evento.event_type is TipoEventoWebhook.DOCUMENTO_RECHAZADO:
    # rechazado con 3001 (rechazo_sri): errores trae el mensaje del SRI
    marcar_rechazado(evento.id_operacion, evento.cod_estado, evento.errores)
elif evento.event_type is TipoEventoWebhook.DOCUMENTO_FALLIDO:
    # rechazado (3002), rechazo_configuracion (4xxx) o error (5xxx): siempre final
    marcar_no_emitido(evento.id_operacion, evento.estado, evento.cod_estado, evento.msg_error, evento.errores)
# OPERACION_REQUIERE_ATENCION: aviso no final (sigue recibido) o evento de prueba

El evento trae estado (tipado en evento.estado_operacion), cod_estado (int, del mismo catalogo que la operacion), msg_error, errores (tupla de textos), fh_autorizacion, tipo_documento (o None) y cuerpo con el cuerpo completo recibido. document.authorized llega con estado autorizado (2001); document.rejected, solo con rechazado y cod_estado 3001 (rechazo_sri); document.failed, con rechazado y 3002 (comprobante_invalido), con rechazo_configuracion (4xxx) o con error (5xxx), y siempre es final. operation.requires_attention es un aviso no final: el documento sigue recibido y el resultado llega despues con otro evento. Un documento cancelado no genera evento.

verify(secretos, cabecera, cuerpo) acepta el cuerpo como bytes o str, uno o varios secretos y tolerancia por defecto de 300 s. Nunca lanza: una cabecera malformada devuelve False.

Cada entrega trae ademas las cabeceras de Standard Webhooks (webhook-id, webhook-timestamp y webhook-signature), firmadas con el mismo secreto, y basta con verificar una de las dos firmas. Con construir_evento_webhook le pasas las cabeceras de la peticion y el SDK verifica Ecuafact-Signature si viene y, si no viene o no es valida, Standard Webhooks:

from ecuafact import construir_evento_webhook, verificar_estandar, verificar_webhook

evento = construir_evento_webhook([secreto_actual, secreto_anterior], request.headers, await request.body())

# Solo la verificacion, sin construir el evento (devuelve True o False):
valido = verificar_webhook(secreto, request.headers, cuerpo)
valido = verificar_estandar(secreto, webhook_id, webhook_timestamp, webhook_signature, cuerpo)

Las cabeceras pueden ser un mapa o una lista de pares, y sus nombres no distinguen mayusculas. Para Standard Webhooks el secreto se usa con o sin el prefijo whsec_ y se decodifica de Base64; un secreto que no es Base64 valido da False. La tolerancia es la misma de 300 s y now fija el reloj en las pruebas, como en verify. firmar_estandar(secreto, webhook_id, unix, cuerpo) calcula el valor de webhook-signature para tus pruebas.

Enums

operacion.estado_operacion (EstadoOperacion: RECIBIDO, AUTORIZADO, RECHAZADO, RECHAZO_CONFIGURACION, ERROR, CANCELADO o DESCONOCIDO), operacion.tipo_comprobante (TipoComprobante), operacion.es_final y operacion.es_autorizado. Tambien hay funciones sueltas que aceptan una operacion, un evento o el texto del estado: estado_operacion(x), es_final(x) y es_autorizado(x). Un valor nuevo del API se lee como DESCONOCIDO (no es final); los campos de texto originales se conservan. CodEstado reune las constantes del catalogo de cod_estado (CodEstado.COMPROBANTE_INVALIDO es 3002, CodEstado.CUPO_AGOTADO es 4004...) y estado_de_cod_estado(codigo) devuelve el EstadoOperacion de un codigo.

Validar sin emitir

validar(comprobante) devuelve ValidacionResultado con valido, cod_estado, msg_error, errores y correlation_id. Con 200 es valido=True (sin cod_estado ni msg_error, errores vacia); con 422 y cod_estado 3002 (CodEstado.COMPROBANTE_INVALIDO) es valido=False y errores trae el detalle por campo. Cualquier otro error lanza la excepcion habitual.

Documentacion

Licencia

MIT.

Metadata

Release files for ecuafact 1.0.0b7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ecuafact 1.0.0b7
File Size Uploaded Provenance Actions
ecuafact-1.0.0b7.tar.gz 85.7 kB Without provenance Details for ecuafact-1.0.0b7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ecuafact 1.0.0b7
File Interpreter ABI Platform Actions
ecuafact-1.0.0b7-py3-none-any.whl Python 3 none any Details for ecuafact-1.0.0b7-py3-none-any.whl

Total release size: 142.3 kB

Release files / ecuafact-1.0.0b7.tar.gz

Download URL ecuafact-1.0.0b7.tar.gz
Size 85.7 kB
Tags Source
SHA-256 checksum
How to use checksums
57b2c106bc15e6db1668410662482cdb9fab9706aba44824b1ec0a380e3b13c8
BLAKE2b-256 checksum
How to use checksums
0327584c1ed93d7504b53d9354a5a8b3ab8afcb836e43d3fbca5590c189627a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / ecuafact-1.0.0b7-py3-none-any.whl

Download URL ecuafact-1.0.0b7-py3-none-any.whl
Size 56.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ffb812d7f32dd2b42cb63755a66372949c4cc289dfb0da3824e436ac7acabb1
BLAKE2b-256 checksum
How to use checksums
103eaae73a603a54cc2ca14b4c2b39dabe77642011d8201e0553cbd6a6fd28a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for ecuafact 1.0.0b7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page