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).
429concod_estado5005 (limite_solicitudes): se reintenta por defecto, respetandoRetry-Aftercon el topemax_retry_delay_ms.retry_rate_limited=Falselo desactiva.- Cualquier otro
429, como el 4004 (cupo_agotado) o uno sin cuerpo, nunca se reintenta. actualizar_perfilno 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_ido un tiempo invalido lanzaEcuafactConfigurationExceptional crearRequestOptions. - La correlacion queda en
resultado.correlation_idy encorrelation_idde cualquier excepcion del SDK (tambien enEcuafactTimeoutExceptionyEcuafactConnectionException). Si el API no devuelveX-Correlation-Id, se expone el que enviaste. reintentos=Trueno 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
timeoutytotal_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), unImpuestoconvalor) 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; cabeceratotalConImpuestosporcodigo+codigoPorcentaje(IVA primero, luego ICE, en orden de aparicion) sumando las lineas;importeTotal= subtotal + IVA + ICE + propina; descuento vacio = 0;propina0 en factura;monedaDOLARen 01, 03 y 04 si falta; un pago sintotalrecibe lo que falta. Nota de debito: IVA = suma del IVA redondeado de cada motivo. Retencion:valorImpuesto,totalSinImpuestos(suma de bases),importeTotal,valorRetenidoy el pago;pagoLocExt01por defecto. - Precision:
Precision(importes=2, cantidades=6, redondeo="HALF_UP"). Modos:HALF_UP,HALF_DOWN,HALF_EVEN,UP,DOWN,CEILING,FLOOR(o la constante dedecimal). Pasa la tuya comoComprobanteBuilder.factura(ruc, estab, pto_emi, precision=Precision(...)). Otra precision puede producir importes que el API rechaza con 422. validar()devuelve una lista deInconsistencia(campo, mensaje, esperado, actual)(str(i)da"info.importeTotal: no coincide con ... (esperado 52.44, actual 52.45)"); no lanza ni bloqueaemitir.- Sin constructor:
calcular_totales(request, precision=None)devuelve una copia con los importes vacios calculados yvalidar_comprobante(request, precision=None)devuelve las inconsistencias; el tipo sale deinfoTributaria.tipoDocumento. - Tarifas:
Iva.TARIFA_0,Iva.TARIFA_5,Iva.TARIFA_8,Iva.TARIFA_15(codigo4),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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.