<!-- source_url: https://docs.mynexusapi.com/v1/guias/sdk-python | last_updated: 2026-11-19 -->

# 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](/v1/guias/sdk).

> [!IMPORTANT]
> 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:

```text
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`](https://pypi.org/project/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](/v1/guias/sandbox).
- [ ] 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.

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

```bash
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](/v1/guias/glosario) de tu API Key.

```python
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](#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](#informacion-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](#validar-antes-de-emitir-opcional)). 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](#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`. |

```python
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](/v1/guias/consulta-contexto), emite una factura, espera el resultado
del SRI con el [seguimiento](/v1/guias/consulta-operacion) y descarga el
[RIDE](/v1/guias/glosario), 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](/v1/guias/glosario) de la serie `estab`-`ptoEmi`. El
script reemplaza `ruc` por el de tu contexto y `fechaEmision` por la fecha de
hoy.

```json
{
  "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](#tipo-de-comprobante).

`estab` y `ptoEmi` deben ser un [establecimiento](/v1/guias/glosario) y un
[punto de emisión](/v1/guias/glosario) de tu emisor; el sandbox crea el
establecimiento `001` con el punto de emisión `001`. Cada campo está explicado en [Factura](/v1/guias/emision-01). Si
prefieres armar el comprobante con métodos en lugar de JSON, usa los
[constructores](#constructores-de-comprobantes).

### 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](#webhooks). Así tu proceso no se queda esperando.

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

```bash
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](/v1/guias/glosario) 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](/v1/guias/errores#codigos-de-resultado-de-una-operacion). |
| `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](#webhooks). 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. |

> [!NOTE]
> 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.

```python
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](#constructores-de-comprobantes) devuelven directamente el modelo de su tipo.

El filtro `tipo_documento` de [`listar_operaciones`](#listado-de-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](#tipo-de-comprobante)) con `/validar` al final, como se detalla en
[Métodos](#metodos). 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:

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

```python
# 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](#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](/v1/guias/emision#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](#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`.

```python
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](/v1/guias/consulta-operacion), 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). |

## 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](/v1/guias/errores#catalogo-de-codestado) 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.

```python
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](/v1/guias/consulta-operacion#que-hacer-segun-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](/v1/guias/webhooks#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](/v1/guias/webhooks-firma#rotacion-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`.

```python
# 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](/v1/guias/webhooks-firma#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`.

```python
evento = construir_evento_webhook(SECRETOS, request.headers, request.get_data())
```

> [!WARNING]
> 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](/v1/guias/webhooks), y el algoritmo de la firma, en
[Verificación de firma](/v1/guias/webhooks-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](#configuracion). | 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`](/v1/guias/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](#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](#idempotencia-y-reintentos). |

| Atributo de `EcuafactApiException` | Tipo | Descripción |
|---|---|---|
| `cod_estado` | `int \| None` | Código numérico del [catálogo de `codEstado`](/v1/guias/errores#catalogo-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`.

```python
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](/v1/guias/errores#catalogo-de-codestado), 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](/v1/guias/limites). |
| 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.

> [!WARNING]
> 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](#informacion-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.

```python
# 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](/v1/guias/limites#cabeceras).

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

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

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

```python
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](/v1/guias/emision) 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`](#validar-sin-emitir) o
[`validar_antes_de_emitir`](#validar-antes-de-emitir-opcional). Todo valor que
asignes se envía tal cual.

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

```python
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](/v1/guias/emision-04).

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

```python
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](/v1/guias/emision-01).

## 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](#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](#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](#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](#listado-de-operaciones)) |
| `get_salud()` | `GET /salud` | `Salud` (`status` y `cuerpo`), como se explica en [Estado del servicio](#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](#estado-del-servicio-y-catalogos). |
| `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](#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](#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](#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](#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](#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](/v1/guias/consulta-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.

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

```python
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](/v1/guias/perfil-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](/v1/guias/consulta-contexto) de tu API Key y `get_consumo()` lee tu
[cupo](/v1/guias/consumo). Ninguna de las dos consume cupo.

```python
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](/v1/guias/consumo#respuesta).

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

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

```python
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](/v1/guias/consulta-contribuyente),
[Contribuyentes por nombre](/v1/guias/consulta-contribuyente-nombre),
[Establecimientos de un RUC](/v1/guias/consulta-establecimientos),
[Validar identificación](/v1/guias/consulta-identificacion) y
[Decodificar clave de acceso](/v1/guias/consulta-clave-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](/v1/guias/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](/v1/guias/catalogos) 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.

```python
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](#errores).

### Estado del servicio

`get_estado_servicio()` devuelve un `EstadoServicio`. Tiene los mismos campos
que la [respuesta de la consulta](/v1/guias/estado-del-servicio#respuesta), 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](/v1/guias/estado-del-servicio#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()`](#estado-del-servicio-y-catalogos).

### 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](/v1/guias/catalogos#catalogos-disponibles). Un
`nombre` vacío lanza `EcuafactSdkException` sin llamar a la API.

| Campo de `IndiceCatalogos` | Tipo | Descripción |
|---|---|---|
| `catalogos` | `list[ResumenCatalogo]` | Catálogos disponibles, en el orden de la ficha técnica del SRI. |

| Campo de `ResumenCatalogo` | Tipo | Descripción |
|---|---|---|
| `nombre` | `str` | Clave del catálogo; es el valor que recibe `get_catalogo`. |
| `descripcion` | `str` | Descripción breve de lo que contiene. |

| Campo de `DetalleCatalogo` | Tipo | Descripción |
|---|---|---|
| `nombre` | `str` | Clave del catálogo. |
| `descripcion` | `str` | Descripción breve del catálogo. |
| `fuente` | `str` | Tabla o anexo de la ficha técnica del SRI de donde proviene. |
| `items` | `list[ItemCatalogo]` | Filas del catálogo. |

| Campo de `ItemCatalogo` | Tipo | Descripción |
|---|---|---|
| `codigo` | `str` | Código tal como va en el comprobante. Envíalo como texto, con sus ceros a la izquierda cuando los tenga. |
| `descripcion` | `str` | Descripción del código. |
| `valor` | `float \| None` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. `None` si el catálogo no lo tiene. |
| `vigente_desde` | `str \| None` | Primer día de vigencia (`yyyy-MM-dd`). `None` si la fila no está acotada por el inicio. |
| `vigente_hasta` | `str \| None` | Último día de vigencia (`yyyy-MM-dd`). `None` si sigue vigente. |
| `atributos` | `dict \| None` | Atributos propios del catálogo. `None` si no hay. |

## Siguientes pasos

- [Factura](/v1/guias/emision-01): revisa todos los campos y las reglas de cálculo para construir tus comprobantes.
- [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta qué significa cada `estado` y cada `codEstado`.
- [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI sin consultar en bucle.
- [Visión general de los SDK](/v1/guias/sdk): compara los cinco SDK y decide entre SDK o HTTP directo.
