Metadata-Version: 2.4
Name: ecuafact
Version: 1.0.0b8
Summary: Cliente oficial en Python del API publico de facturacion electronica Ecuafact (contrato v1).
Author: Ecuanexus
License-Expression: MIT
Project-URL: Documentation, https://docsapi.ecuafact.com/v1/guias/sdk-python
Project-URL: Homepage, https://docsapi.ecuafact.com/v1/guias/sdk-python
Keywords: ecuafact,sri,facturacion-electronica,ecuador,api,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.6
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# 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, listado de operaciones, logo del perfil, administracion de destinos de webhooks y verificacion de su firma. Requiere Python 3.10+. Incluye `py.typed`.

Versión preliminar actual: `1.0.0b8`.

## Instalacion

```bash
pip install "ecuafact>=1.0.0b8"
```

## Uso

```python
from decimal import Decimal
from ecuafact import ComprobanteBuilder, EcuafactClient, EcuafactClientOptions

# 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
))

# El tipo del modelo elige la ruta: este FacturaRequest va a POST .../facturas.
factura = (
    ComprobanteBuilder.factura("0123456789001", "002", "001")
    .referencias("MiERP", "FACTURA-2026-0001")
    .info(total_sin_impuestos=Decimal("10.00"), importe_total=Decimal("11.50"))
    .construir()
)  # sin lineas ni pagos, solo para ilustrar; la API decide si el cuerpo es valido
resultado = client.emitir(factura)
# 202: "recibido" con cod_estado 1001 (sin clave de acceso) o 1002 (con clave_acceso), o ya "autorizado" con 2001:
# decide por estado y cod_estado
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` (`None` solo en un rechazo sincronico, que se lanza como excepcion), `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`. `secuencial` es opcional: si lo omites, la plataforma asigna el siguiente; con un valor de 1 a 999999999 se usa ese numero.

### Multi-RUC

```python
ruc = client.para("0123456789001")
ruc.validar(comprobante)                          # llama a /validar, 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 HTTPS del despliegue, sin usuario, consulta, fragmento ni `/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` |
| `max_response_bytes` | 32 MiB (100 MiB en descargas) | Tope en bytes de la respuesta; `None` o `0` lo desactiva. Al superarlo lanza `EcuafactResponseTooLargeException` (`limite`, `bytes_leidos`) |
| `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 |
| `validar_antes_de_emitir` | `False` | `True` hace que `emitir` llame antes a `/validar` y no envie la emision si la API la rechaza (dos peticiones por emision) |
| `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.

### Tipo de comprobante

Hay un modelo de solicitud por tipo de comprobante, igual que hay un endpoint por tipo, y el tipo del modelo elige la
ruta. No existe un campo `tipoDocumento` en el cuerpo ni un argumento `tipo`.

| Modelo | Ruta | Modelos propios de su cuerpo |
|---|---|---|
| `FacturaRequest` | `facturas` | `InfoFactura`, `DetalleCompraVenta` |
| `LiquidacionCompraRequest` | `liquidaciones-compra` | `InfoLiquidacionCompra`, `DetalleCompraVenta` |
| `NotaCreditoRequest` | `notas-credito` | `InfoNotaCredito`, `DetalleNotaCredito` |
| `NotaDebitoRequest` | `notas-debito` | `InfoNotaDebito`, `Motivo` |
| `GuiaRemisionRequest` | `guias-remision` | `InfoGuiaRemision`, `Destinatario`, `DetalleGuia` |
| `RetencionRequest` | `retenciones` | `InfoComprobanteRetencion`, `DocsSustento`, `RetencionLinea`, `ImpuestoDocSustento` |

Los seis comparten `InfoTributaria`, `Pago`, `Impuesto` y `CampoAdicional`. Cada modelo tiene solo las propiedades de
su esquema del contrato, con su nulabilidad. Las propiedades que el contrato marca como obligatorias se documentan con
`Obligatorio.` en su descripcion (`Field.description` y `json_schema_extra={"obligatorio": True}`), pero el SDK no las
exige: cualquier combinacion se construye sin error local y se envia tal cual, y la API responde 422 con `errores`. Una
propiedad que el contrato no define se conserva y se serializa (`extra="allow"`), para que la API la rechace. Las
respuestas se leen de forma permisiva: un campo nuevo del API no rompe tu codigo.

`emitir`, `emitir_en`, `validar` y `validar_en` reciben el modelo tipado. Si tienes un JSON o un `dict`, conviertelo con el modelo de
su tipo (`FacturaRequest.model_validate(datos)`). Cualquier otro objeto lanza `EcuafactTipoComprobanteException` antes de
llamar al API. El filtro `tipo_documento` de `listar_operaciones` si acepta un `TipoComprobante`, su nombre o su codigo.

## 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 |
| `validar_antes_de_emitir` | `None` (usa `options.validar_antes_de_emitir`) | Solo en `emitir`/`emitir_en`: `True` o `False` reemplaza el valor del cliente en esta llamada |

```python
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. Cada uno arma el modelo de su tipo: `FacturaRequest` (`01`), `LiquidacionCompraRequest` (`03`),
`NotaCreditoRequest` (`04`), `NotaDebitoRequest` (`05`), `GuiaRemisionRequest` (`06`) y `RetencionRequest` (`07`). Solo ayudan a armar
el cuerpo: no calculan, no completan valores y no lanzan por reglas de negocio. Campos requeridos, formatos,
catalogos, topes e importes los valida unicamente la API (usa `validar` o `validar_antes_de_emitir`).

```python
from ecuafact import ComprobanteBuilder

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", ("4", 15))
    .moneda("DOLAR")
    .pago("01", "43.13")
    .construir()
)
client.validar(factura)                      # la API decide
client.emitir(factura, "FACTURA-2026-0001")
```

- **Tus valores viajan tal cual.** Todo importe que asignes (en `linea(...)`, `detalle(DetalleCompraVenta(...))` (`DetalleNotaCredito` en la nota de credito),
  `info(importe_total=...)`, `pago(forma, total)`, un `Impuesto` con `valor`) se envia sin cambios; el builder no
  tiene valores por defecto ni catalogos. La tarifa es `Tarifa("4", 15)`, la tupla `("4", 15)` o un `Impuesto`; el ICE
  se pasa con `linea(..., ice=("3011", 10))`.
- **Retirado** (cambio incompatible, ver el changelog): `calcular_totales`, `validar_comprobante`, `validar()` del
  builder, `Inconsistencia`, `Precision` y las constantes `Iva`.

| 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`,
`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 |
| `EcuafactTipoComprobanteException` | Tipo ausente, ambiguo o en conflicto | Indica `tipo` |
| `EcuafactResponseTooLargeException` | Respuesta mayor que `max_response_bytes` | Sube o desactiva el tope; no se reintenta |
| `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:

```python
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`.

## Listar operaciones

`listar_operaciones(...)` (`GET /v1/operaciones`) devuelve una `PaginaComprobantes` con los comprobantes emitidos de un
contribuyente. No consume cupo. `identificacion` es obligatoria (si falta, se usa la del cliente); los demas filtros son opcionales y se pasan por nombre: `desde` y `hasta` (`yyyy-MM-dd` o `datetime.date`), `tipo_documento` (`TipoComprobante`, codigo o
nombre), `buscar` (numero, clave, contraparte o referencia), `pagina` (desde 1) y `tamano_pagina` (de 1 a 100).

```python
pagina = 1
while True:
    resultado = client.listar_operaciones(
        identificacion="0123456789001",
        desde="2026-11-01",
        hasta="2026-11-30",
        tipo_documento=TipoComprobante.FACTURA,
        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
```

Cada fila (`Comprobante`) trae `clave_acceso`, `numero_documento`, `tipo_documento`, `fecha_emision`,
`identificacion_contraparte`, `razon_social_contraparte`, `total`, `estado`, `cod_estado`, `msg_error`, `errores` y
`fh_autorizacion`. `client.para(identificacion).listar_operaciones(...)` hace lo mismo con la identificacion fija.

## Estado del servicio

`get_salud()` (`GET /salud`) comprueba que el servicio responde y devuelve `Salud` con `status` y `cuerpo`. No requiere
API Key. Ante una respuesta que no es 2xx lanza la excepcion correspondiente.

## Destinos de webhooks

Los destinos se administran con `/v1/webhooks/destinos...`. Los metodos que cambian el estado de un destino no se
reintentan automaticamente.

| Metodo | Operacion |
|---|---|
| `listar_destinos_webhook()` | Lista los destinos (`list[WebhookEndpoint]`). |
| `crear_destino_webhook(url, eventos, ruc=None)` | Crea un destino. Devuelve `secreto_una_vez`. |
| `get_destino_webhook(id)` | Consulta un destino. |
| `actualizar_eventos_webhook(id, eventos)` | Reemplaza los eventos suscritos. |
| `rotar_secreto_webhook(id)` | Rota el secreto. Devuelve el nuevo `secreto_una_vez`. |
| `probar_webhook(id)` | Envia un evento de prueba (202). |
| `pausar_webhook(id)`, `reanudar_webhook(id)`, `deshabilitar_webhook(id)` | Cambian el estado del destino. |
| `listar_entregas_webhook(id)` | Lista las entregas (`list[WebhookDelivery]`). |
| `listar_intentos_entrega_webhook(id, entrega_id)` | Lista los intentos de una entrega (`entrega_id` es el `public_id` de la entrega). |
| `reintentar_entrega_webhook(id, evento_id)` | Reencola una entrega fallida o rechazada (`evento_id` es el `event_id` de la entrega). |

```python
destino = client.crear_destino_webhook(
    "https://miempresa.com/webhooks/ecuafact",
    [TipoEventoWebhook.DOCUMENTO_AUTORIZADO, TipoEventoWebhook.DOCUMENTO_RECHAZADO, TipoEventoWebhook.DOCUMENTO_FALLIDO],
    ruc="0123456789001",  # opcional: sin ruc, el destino recibe todos los RUC
)
guardar_secreto(destino.public_id, destino.secreto_una_vez)  # el API no vuelve a mostrar el secreto
client.probar_webhook(destino.public_id)
```

`id` es el `public_id` del destino (UUID, texto o `uuid.UUID`). Los metodos que no devuelven datos
(`actualizar_eventos_webhook`, `probar_webhook`, `pausar_webhook`, `reanudar_webhook`, `deshabilitar_webhook` y
`reintentar_entrega_webhook`) devuelven `None`; un error del API se lanza como en el resto de los metodos (por ejemplo
`EcuafactNotFoundException` con 404).

## Webhooks

```python
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`), `ruc` (el contribuyente emisor, para enrutar un destino compartido por varios RUC), `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:

```python
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)` llama siempre al endpoint `/validar` del tipo (el SDK no valida nada localmente) y devuelve `ValidacionResultado` con `valido`, `cod_estado`, `msg_error`, `errores`,
`advertencias` y `correlation_id`. Con 200 lee `valido` y `advertencias` del cuerpo (`valido=True`, sin `cod_estado` ni
`msg_error`, `errores` vacia; `advertencias` son avisos que no impiden emitir); 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.

### Validar antes de emitir (opcional)

`emitir` y `emitir_en` envian el comprobante directo: si la API lo rechaza lanzan `EcuafactValidationException`
(422) con el detalle en `errores`. Para comprobarlo antes de cada emision activa `validar_antes_de_emitir`
(por defecto `False`, para no duplicar las peticiones en produccion), en el cliente o solo en una llamada:

```python
client = EcuafactClient(EcuafactClientOptions(validar_antes_de_emitir=True))
# o solo en una llamada:
resultado = client.emitir_en(ruc, comprobante, "FACTURA-2026-0001", opciones=RequestOptions(validar_antes_de_emitir=True))
print(resultado.advertencias)   # avisos de /validar; no bloquean
```

Con `True`, cada emision hace dos peticiones: primero `/validar` y, si `valido` es `True` y no hay `errores`, la
emision. Si no es valido, lanza la misma `EcuafactValidationException` (422, `cod_estado` 3002) **sin enviar la
emision**. Con `False`, una sola peticion. La opcion de `RequestOptions` (`None` usa la del cliente) reemplaza a la
del cliente en ambos sentidos.

## Documentacion

- [Guia del SDK Python](https://docsapi.ecuafact.com/v1/guias/sdk-python)

## Licencia

MIT.
