trevol 0.1.0__tar.gz

trevol-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage

trevol-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Registro de cambios
+
+El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el versionado, [SemVer](https://semver.org/lang/es/): antes
+de la 1.0, un cambio incompatible sube el número menor.
+
+## [0.1.0] — sin publicar
+
+Primera versión (API `2026-10-22`).
+
+- Cliente `Trevol` con un recurso por etiqueta de la API (`invoices`, `credit_notes`, `debit_notes`, `support_documents`, `payrolls`,
+  `radian_events`, `webhook_endpoints`, `events`, `requests`, `balance`, `general`…), modelos pydantic generados de la especificación.
+- `Idempotency-Key` automática (la misma en los reintentos), reintentos con espera creciente que respetan `Retry-After`, errores tipados por
+  `code`, entorno deducido del prefijo de la llave, `Trevol-Version` fijada.
+- `paginate` (iterador), descargas de PDF, XML y ZIP como `bytes`, `Webhook.verify` y `Webhook.event_data` (Standard Webhooks).

trevol-0.1.0/GENERADO.md

@@ -0,0 +1,14 @@
+# Código generado
+
+**No edites `src/trevol/_generado/`**: `sdks/generar.sh` la borra y la vuelve a escribir entera. La capa propia (cliente,
+reintentos, errores, paginación, webhooks) vive fuera de esa carpeta.
+
+| | |
+|---|---|
+| Generador | OpenAPI Generator 7.26.0 (`python`) |
+| Especificación | `especificacion/openapi.sdk.enums-abiertos.json` (variante 3.0.3 de `docs/api/openapi.json`, versión de la API 2026-10-22) |
+| sha256 de la especificación | `ca431c24f76cc576b9f989aa4c9df300f5df85fdce051a0704558fae65374bd1` |
+| Configuración | `openapi-generator.yaml` |
+
+Regenerar (desde el monorepo de Trevol): `sdks/generar.sh python`. Comprobar que lo del repositorio es lo que sale de la
+especificación: `sdks/generar.sh --comprobar python`.

trevol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Montclair (Trevol)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trevol-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: trevol
+Version: 0.1.0
+Summary: SDK de Python para la API de Trevol: facturación electrónica ante la DIAN (Colombia). Python SDK for the Trevol API.
+Project-URL: Documentation, https://platform.trevol.si/docs
+Project-URL: Repository, https://github.com/trevol-si/trevol-python
+Project-URL: Issues, https://github.com/trevol-si/trevol-python/issues
+Author: Joshua Montclair (Trevol)
+License-Expression: MIT
+License-File: LICENSE
+Keywords: colombia,dian,factura electronica,nomina electronica,sdk,trevol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.5.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: standardwebhooks<2,>=1.1.0
+Requires-Dist: typing-extensions>=4.7.1
+Requires-Dist: urllib3<3,>=2.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov==7.0.0; extra == 'dev'
+Requires-Dist: pytest==8.4.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# trevol
+
+SDK de Python para la **API de Trevol**: facturación electrónica, documento soporte, documento equivalente, nómina electrónica y eventos
+RADIAN ante la DIAN (Colombia). Documentación: <https://platform.trevol.si/docs>.
+
+> **In English.** Python SDK for the Trevol API (Colombian e-invoicing, DIAN). Python ≥ 3.10, typed (pydantic v2) models generated from the
+> OpenAPI spec (OpenAPI Generator), plus a thin hand-written layer: automatic `Idempotency-Key` (the same one on retries), retries with
+> exponential backoff honouring `Retry-After`, typed errors by problem+json `code`, environment inferred from the key prefix (`tvl_test_` =
+> DIAN test environment, `tvl_live_` = production), pinned `Trevol-Version`, Standard Webhooks signature verification, cursor pagination
+> iterators and PDF/XML/ZIP downloads (as `bytes`). Docs are in Spanish like the API.
+
+**Versión 0.1.0** — API `2026-10-22`. Licencia MIT.
+
+## Instalación
+
+```sh
+pip install trevol
+```
+
+Necesita Python 3.10 o más nuevo. Dependencias: `urllib3`, `pydantic>=2`, `python-dateutil`, `typing-extensions` y
+[`standardwebhooks`](https://pypi.org/project/standardwebhooks/).
+
+## Uso
+
+La llave de la API se crea en la consola de desarrolladores (<https://platform.trevol.si/llaves>) y se guarda en el entorno de tu **servidor**:
+`TREVOL_API_KEY`. Una llave `tvl_test_…` llama a la habilitación de la DIAN; una `tvl_live_…`, a producción. El SDK deduce el entorno del
+prefijo (`trevol.environment`).
+
+```python
+import os
+from trevol import Trevol, TrevolError, ValidationError, Webhook
+
+trevol = Trevol()  # lee TREVOL_API_KEY; tvl_test_… → trevol.environment == "test"
+
+try:
+    factura = trevol.invoices.create_invoice(
+        invoice_input={
+            "external_id": "VENTA-2026-000123",
+            "customer": {"final_consumer": True},
+            "items": [{"description": "Café especial 500 g", "quantity": "1", "unit_price": "32000", "taxes": [{"code": "01", "rate": "19"}]}],
+            "payment": {"form": "cash", "methods": [{"code": "10"}]},
+        },
+        idempotency_key="VENTA-2026-000123",  # opcional: si falta, el SDK pone una y la repite en los reintentos
+    )
+    if factura.status == "processing":
+        pass  # 202: la DIAN no contestó; Trevol lo termina y avisa por webhook. NO crees otro documento para la misma venta.
+except ValidationError as e:
+    for x in e.errors:
+        print(x.pointer, x.message)
+except TrevolError as e:
+    print(e.code, e.request_id)
+
+# Todas las páginas de un listado, perezosamente
+for f in trevol.paginate(lambda cursor: trevol.invoices.list_invoices(limit=100, starting_after=cursor)):
+    print(f.id, f.status)
+
+# Los archivos llegan como bytes
+pdf: bytes = trevol.invoices.download_invoice_pdf(id="inv_…")
+
+# Un webhook: verifica sobre el CUERPO CRUDO
+evento = Webhook(os.environ["TREVOL_WEBHOOK_SECRET"]).verify(request.get_data(), request.headers)
+```
+
+Los métodos son los `operationId` de la [especificación](https://platform.trevol.si/docs/api) en `snake_case` (`create_invoice`,
+`list_invoices`, `retrieve_invoice`, `correct_invoice`, `send_invoice`, `download_invoice_pdf`…) y el cuerpo es el nombre del esquema en
+`snake_case` (`invoice_input`). Puedes pasar un `dict` (como arriba) o el modelo (`InvoiceInput(...)`). Los campos se escriben **igual que en la
+API** (`external_id`), y los importes y las fechas viajan como texto (`"32000.50"`, `"2026-10-31"`).
+
+## Lo que conviene saber
+
+### Idempotencia: manda `external_id` y tu propia clave
+
+El SDK genera una `Idempotency-Key` por llamada y **la repite en todos los reintentos de esa llamada**. Pero si tu proceso muere y vuelves a
+llamar, saldrá otra clave y, si no mandaste `external_id` (es opcional), podría duplicarse el documento. Por eso:
+
+- manda siempre `external_id` (tu id de la venta), y
+- pasa una `idempotency_key` derivada de tu venta (`idempotency_key="VENTA-2026-000123"`).
+
+Ante un `ConflictError` con `code == "external_id_in_use"`, el documento ya existe: usa `error.problem["existing_id"]`. Todo error lleva la
+`idempotency_key` que se usó (`error.idempotency_key`) para reintentar más tarde con la misma. Un `APIConnectionError` también.
+
+### Respuestas 202 (`processing`, `sending`, `validating`, `contingency`)
+
+No son errores ni se reintentan: se devuelven como el modelo de la respuesta. **No crees otro documento**: espera el webhook o consulta con
+`retrieve_invoice`; repetir la misma llamada con la misma `Idempotency-Key` continúa el mismo documento. El PDF y el ZIP llegan después del
+`201` (evento `invoice.delivered`, o `delivery.status == "completed"`).
+
+### Reintentos
+
+Hasta 2 reintentos (3 intentos) con espera creciente (0,5 s, 1 s, 2 s… con tope de 8 s y un poco de azar) ante un error de red, 429, 500,
+502, 503, 504, un 409 `request_in_progress` o `previous_event_pending`, y todo problema que diga `retryable: true` (salvo el 402). Respeta
+`Retry-After`; si pide más de `max_retry_after` (60 s) no espera y lanza el error con `error.retry_after`. Las operaciones sin
+`Idempotency-Key` (crear un endpoint, `…/send`, `DELETE`) solo se reintentan con 429. Los 202 y los errores finales (400, 401, 402, 403, 404,
+422 y los 409 `invalid_state`, `external_id_in_use`, `duplicate_document`) **nunca** se reintentan. Los reintentos de `urllib3` están apagados:
+el SDK es el único que reintenta.
+
+### La versión de la API
+
+El SDK fija `Trevol-Version: 2026-10-22` en cada petición. **Ojo:** una llave creada con la versión `2026-10-21` que empiece a usar este SDK
+pasa a `2026-10-22` (el encabezado manda): recibe `202 processing` donde antes recibía `503`. Si todavía no quieres ese cambio:
+`Trevol(api_version="2026-10-21")`. Más en <https://platform.trevol.si/docs/versiones>.
+
+### Errores tipados
+
+`TrevolError` es la base; las clases salen del `code` del problem+json: `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`,
+`InvalidRequestError`, `IdempotencyError`, `ValidationError` (con `errors`: `field`, `pointer`, `message`), `ConflictError`,
+`PreconditionError`, `DianRejectedError` (con `problem["document"]` y `problem["rules"]`), `BalanceError`, `RateLimitError`,
+`DianUnavailableError` e `InternalServerError`. Un `code` que el SDK todavía no conoce llega como `TrevolError` con ese `code`: nunca
+rompe. Además: `APIConnectionError` (no hubo respuesta), `ConfigurationError` (mal uso, antes de llamar) y `WebhookVerificationError`.
+Cada error tiene `status`, `code`, `type`, `title`, `detail`, `request_id`, `retryable`, `retry_after`, `errors`, `idempotency_key`,
+`problem` (el cuerpo completo) y `headers` (los de la respuesta). Ninguno incluye tu llave (ni su `repr`, ni su traceback).
+
+### Webhooks
+
+```python
+from flask import Flask, request
+from trevol import Webhook, WebhookVerificationError
+
+app = Flask(__name__)
+wh = Webhook(os.environ["TREVOL_WEBHOOK_SECRET"])  # whsec_…
+
+@app.post("/webhooks/trevol")
+def recibir():
+    try:
+        evento = wh.verify(request.get_data(), request.headers)   # el cuerpo CRUDO, no request.json
+    except WebhookVerificationError:
+        return "", 400
+    # Deduplica por evento.id (también llega en la cabecera webhook-id): la verificación no evita repeticiones.
+    datos = wh.event_data(evento)   # el modelo según evento.type (p. ej. DocumentEventData)
+    return "", 200
+```
+
+En FastAPI usa `await request.body()`; en Django, `request.body`. La firma se calcula sobre los **bytes exactos**. `verify` acepta cualquier mapa de
+cabeceras (Flask, Django, Starlette, `dict`) y el cuerpo como `str` o `bytes`; tolera 5 minutos hacia atrás y hacia adelante en `webhook-timestamp`.
+
+### Estado y cabeceras de la respuesta
+
+Cada método tiene una variante `…_with_http_info` que devuelve `ApiResponse` con `status_code`, `headers` y `data`:
+`r = trevol.invoices.create_invoice_with_http_info(...); r.headers["request-id"]; r.headers["idempotent-replayed"]; r.data`.
+
+### Cabeceras propias por llamada
+
+Cada método acepta `_headers={...}` (se mezcla con las del SDK) y `_request_timeout=` (segundos).
+
+## Opciones
+
+```python
+Trevol(
+    api_key,
+    api_version="2026-10-22",   # Trevol-Version en cada petición
+    max_retries=2,              # 0 los apaga
+    timeout=65.0,               # segundos por intento
+    max_retry_after=60.0,       # segundos
+    base_url="https://api.trevol.si/v1",
+    environment="test",         # si la llave no coincide: ConfigurationError antes de llamar
+    proxy=None,                 # p. ej. "http://proxy.miempresa.co:3128"
+)
+```
+
+## Cómo está hecho
+
+- `src/trevol/_generado/` lo escribe [OpenAPI Generator](https://openapi-generator.tech) 7.26.0 (`python`, pydantic v2, urllib3) desde la
+  especificación pública y **no se edita** (ver `GENERADO.md`). Para que un valor nuevo de un `enum` en lo que la API devuelve no rompa a quien
+  ya integró, los modelos de respuesta se generan sin `enum` (los valores conocidos quedan en la descripción).
+- Lo propio (`cliente.py`, `transporte.py`, `errores.py`, `paginacion.py`, `webhooks.py`) vive fuera y solo usa los puntos de extensión del
+  código generado (una subclase de `ApiClient`).
+- Las pruebas: `pip install -e ".[dev]" && pytest` (unitarias sin red contra un servidor HTTP local, con los mismos casos de los demás SDK en
+  `pruebas/datos/`); `TREVOL_PRISM_URL=http://127.0.0.1:4010 pytest pruebas/prism pruebas/fragmentos` contra un servidor simulado
+  (`npx @stoplight/prism-cli mock pruebas/datos/openapi.json -p 4010`) que valida cada petición contra la especificación, y que además corre
+  como programa cada fragmento de código de la documentación.
+- `python pruebas/humo/humo.py` es la prueba de humo **real** (solo con una llave `tvl_test_`; no emite documentos).
+
+## Licencia
+
+MIT © 2026 Joshua Montclair (Trevol).

trevol-0.1.0/README.md

@@ -0,0 +1,175 @@
+# trevol
+
+SDK de Python para la **API de Trevol**: facturación electrónica, documento soporte, documento equivalente, nómina electrónica y eventos
+RADIAN ante la DIAN (Colombia). Documentación: <https://platform.trevol.si/docs>.
+
+> **In English.** Python SDK for the Trevol API (Colombian e-invoicing, DIAN). Python ≥ 3.10, typed (pydantic v2) models generated from the
+> OpenAPI spec (OpenAPI Generator), plus a thin hand-written layer: automatic `Idempotency-Key` (the same one on retries), retries with
+> exponential backoff honouring `Retry-After`, typed errors by problem+json `code`, environment inferred from the key prefix (`tvl_test_` =
+> DIAN test environment, `tvl_live_` = production), pinned `Trevol-Version`, Standard Webhooks signature verification, cursor pagination
+> iterators and PDF/XML/ZIP downloads (as `bytes`). Docs are in Spanish like the API.
+
+**Versión 0.1.0** — API `2026-10-22`. Licencia MIT.
+
+## Instalación
+
+```sh
+pip install trevol
+```
+
+Necesita Python 3.10 o más nuevo. Dependencias: `urllib3`, `pydantic>=2`, `python-dateutil`, `typing-extensions` y
+[`standardwebhooks`](https://pypi.org/project/standardwebhooks/).
+
+## Uso
+
+La llave de la API se crea en la consola de desarrolladores (<https://platform.trevol.si/llaves>) y se guarda en el entorno de tu **servidor**:
+`TREVOL_API_KEY`. Una llave `tvl_test_…` llama a la habilitación de la DIAN; una `tvl_live_…`, a producción. El SDK deduce el entorno del
+prefijo (`trevol.environment`).
+
+```python
+import os
+from trevol import Trevol, TrevolError, ValidationError, Webhook
+
+trevol = Trevol()  # lee TREVOL_API_KEY; tvl_test_… → trevol.environment == "test"
+
+try:
+    factura = trevol.invoices.create_invoice(
+        invoice_input={
+            "external_id": "VENTA-2026-000123",
+            "customer": {"final_consumer": True},
+            "items": [{"description": "Café especial 500 g", "quantity": "1", "unit_price": "32000", "taxes": [{"code": "01", "rate": "19"}]}],
+            "payment": {"form": "cash", "methods": [{"code": "10"}]},
+        },
+        idempotency_key="VENTA-2026-000123",  # opcional: si falta, el SDK pone una y la repite en los reintentos
+    )
+    if factura.status == "processing":
+        pass  # 202: la DIAN no contestó; Trevol lo termina y avisa por webhook. NO crees otro documento para la misma venta.
+except ValidationError as e:
+    for x in e.errors:
+        print(x.pointer, x.message)
+except TrevolError as e:
+    print(e.code, e.request_id)
+
+# Todas las páginas de un listado, perezosamente
+for f in trevol.paginate(lambda cursor: trevol.invoices.list_invoices(limit=100, starting_after=cursor)):
+    print(f.id, f.status)
+
+# Los archivos llegan como bytes
+pdf: bytes = trevol.invoices.download_invoice_pdf(id="inv_…")
+
+# Un webhook: verifica sobre el CUERPO CRUDO
+evento = Webhook(os.environ["TREVOL_WEBHOOK_SECRET"]).verify(request.get_data(), request.headers)
+```
+
+Los métodos son los `operationId` de la [especificación](https://platform.trevol.si/docs/api) en `snake_case` (`create_invoice`,
+`list_invoices`, `retrieve_invoice`, `correct_invoice`, `send_invoice`, `download_invoice_pdf`…) y el cuerpo es el nombre del esquema en
+`snake_case` (`invoice_input`). Puedes pasar un `dict` (como arriba) o el modelo (`InvoiceInput(...)`). Los campos se escriben **igual que en la
+API** (`external_id`), y los importes y las fechas viajan como texto (`"32000.50"`, `"2026-10-31"`).
+
+## Lo que conviene saber
+
+### Idempotencia: manda `external_id` y tu propia clave
+
+El SDK genera una `Idempotency-Key` por llamada y **la repite en todos los reintentos de esa llamada**. Pero si tu proceso muere y vuelves a
+llamar, saldrá otra clave y, si no mandaste `external_id` (es opcional), podría duplicarse el documento. Por eso:
+
+- manda siempre `external_id` (tu id de la venta), y
+- pasa una `idempotency_key` derivada de tu venta (`idempotency_key="VENTA-2026-000123"`).
+
+Ante un `ConflictError` con `code == "external_id_in_use"`, el documento ya existe: usa `error.problem["existing_id"]`. Todo error lleva la
+`idempotency_key` que se usó (`error.idempotency_key`) para reintentar más tarde con la misma. Un `APIConnectionError` también.
+
+### Respuestas 202 (`processing`, `sending`, `validating`, `contingency`)
+
+No son errores ni se reintentan: se devuelven como el modelo de la respuesta. **No crees otro documento**: espera el webhook o consulta con
+`retrieve_invoice`; repetir la misma llamada con la misma `Idempotency-Key` continúa el mismo documento. El PDF y el ZIP llegan después del
+`201` (evento `invoice.delivered`, o `delivery.status == "completed"`).
+
+### Reintentos
+
+Hasta 2 reintentos (3 intentos) con espera creciente (0,5 s, 1 s, 2 s… con tope de 8 s y un poco de azar) ante un error de red, 429, 500,
+502, 503, 504, un 409 `request_in_progress` o `previous_event_pending`, y todo problema que diga `retryable: true` (salvo el 402). Respeta
+`Retry-After`; si pide más de `max_retry_after` (60 s) no espera y lanza el error con `error.retry_after`. Las operaciones sin
+`Idempotency-Key` (crear un endpoint, `…/send`, `DELETE`) solo se reintentan con 429. Los 202 y los errores finales (400, 401, 402, 403, 404,
+422 y los 409 `invalid_state`, `external_id_in_use`, `duplicate_document`) **nunca** se reintentan. Los reintentos de `urllib3` están apagados:
+el SDK es el único que reintenta.
+
+### La versión de la API
+
+El SDK fija `Trevol-Version: 2026-10-22` en cada petición. **Ojo:** una llave creada con la versión `2026-10-21` que empiece a usar este SDK
+pasa a `2026-10-22` (el encabezado manda): recibe `202 processing` donde antes recibía `503`. Si todavía no quieres ese cambio:
+`Trevol(api_version="2026-10-21")`. Más en <https://platform.trevol.si/docs/versiones>.
+
+### Errores tipados
+
+`TrevolError` es la base; las clases salen del `code` del problem+json: `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`,
+`InvalidRequestError`, `IdempotencyError`, `ValidationError` (con `errors`: `field`, `pointer`, `message`), `ConflictError`,
+`PreconditionError`, `DianRejectedError` (con `problem["document"]` y `problem["rules"]`), `BalanceError`, `RateLimitError`,
+`DianUnavailableError` e `InternalServerError`. Un `code` que el SDK todavía no conoce llega como `TrevolError` con ese `code`: nunca
+rompe. Además: `APIConnectionError` (no hubo respuesta), `ConfigurationError` (mal uso, antes de llamar) y `WebhookVerificationError`.
+Cada error tiene `status`, `code`, `type`, `title`, `detail`, `request_id`, `retryable`, `retry_after`, `errors`, `idempotency_key`,
+`problem` (el cuerpo completo) y `headers` (los de la respuesta). Ninguno incluye tu llave (ni su `repr`, ni su traceback).
+
+### Webhooks
+
+```python
+from flask import Flask, request
+from trevol import Webhook, WebhookVerificationError
+
+app = Flask(__name__)
+wh = Webhook(os.environ["TREVOL_WEBHOOK_SECRET"])  # whsec_…
+
+@app.post("/webhooks/trevol")
+def recibir():
+    try:
+        evento = wh.verify(request.get_data(), request.headers)   # el cuerpo CRUDO, no request.json
+    except WebhookVerificationError:
+        return "", 400
+    # Deduplica por evento.id (también llega en la cabecera webhook-id): la verificación no evita repeticiones.
+    datos = wh.event_data(evento)   # el modelo según evento.type (p. ej. DocumentEventData)
+    return "", 200
+```
+
+En FastAPI usa `await request.body()`; en Django, `request.body`. La firma se calcula sobre los **bytes exactos**. `verify` acepta cualquier mapa de
+cabeceras (Flask, Django, Starlette, `dict`) y el cuerpo como `str` o `bytes`; tolera 5 minutos hacia atrás y hacia adelante en `webhook-timestamp`.
+
+### Estado y cabeceras de la respuesta
+
+Cada método tiene una variante `…_with_http_info` que devuelve `ApiResponse` con `status_code`, `headers` y `data`:
+`r = trevol.invoices.create_invoice_with_http_info(...); r.headers["request-id"]; r.headers["idempotent-replayed"]; r.data`.
+
+### Cabeceras propias por llamada
+
+Cada método acepta `_headers={...}` (se mezcla con las del SDK) y `_request_timeout=` (segundos).
+
+## Opciones
+
+```python
+Trevol(
+    api_key,
+    api_version="2026-10-22",   # Trevol-Version en cada petición
+    max_retries=2,              # 0 los apaga
+    timeout=65.0,               # segundos por intento
+    max_retry_after=60.0,       # segundos
+    base_url="https://api.trevol.si/v1",
+    environment="test",         # si la llave no coincide: ConfigurationError antes de llamar
+    proxy=None,                 # p. ej. "http://proxy.miempresa.co:3128"
+)
+```
+
+## Cómo está hecho
+
+- `src/trevol/_generado/` lo escribe [OpenAPI Generator](https://openapi-generator.tech) 7.26.0 (`python`, pydantic v2, urllib3) desde la
+  especificación pública y **no se edita** (ver `GENERADO.md`). Para que un valor nuevo de un `enum` en lo que la API devuelve no rompa a quien
+  ya integró, los modelos de respuesta se generan sin `enum` (los valores conocidos quedan en la descripción).
+- Lo propio (`cliente.py`, `transporte.py`, `errores.py`, `paginacion.py`, `webhooks.py`) vive fuera y solo usa los puntos de extensión del
+  código generado (una subclase de `ApiClient`).
+- Las pruebas: `pip install -e ".[dev]" && pytest` (unitarias sin red contra un servidor HTTP local, con los mismos casos de los demás SDK en
+  `pruebas/datos/`); `TREVOL_PRISM_URL=http://127.0.0.1:4010 pytest pruebas/prism pruebas/fragmentos` contra un servidor simulado
+  (`npx @stoplight/prism-cli mock pruebas/datos/openapi.json -p 4010`) que valida cada petición contra la especificación, y que además corre
+  como programa cada fragmento de código de la documentación.
+- `python pruebas/humo/humo.py` es la prueba de humo **real** (solo con una llave `tvl_test_`; no emite documentos).
+
+## Licencia
+
+MIT © 2026 Joshua Montclair (Trevol).

trevol-0.1.0/pruebas/conftest.py

@@ -0,0 +1,127 @@
+"""Ayudas de las pruebas: un servidor HTTP falso en localhost (pasa por urllib3 de verdad) y un cliente con reloj y azar inyectados."""
+
+from __future__ import annotations
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+import pytest
+
+from trevol import Trevol
+
+DATOS = Path(__file__).parent / "datos"
+HEX = "3f0c1a2b" * 8
+LLAVE_TEST = "tvl_test_" + "a1" * 32
+LLAVE_LIVE = "tvl_live_" + "b2" * 32
+DOCUMENTO = {"id": "inv_" + HEX[:32], "object": "invoice", "environment": "test", "status": "accepted", "number": "SETP990012345",
+             "external_id": "VENTA-2026-000123"}
+ENTRADA_FACTURA = {"external_id": "VENTA-2026-000123", "customer": {"final_consumer": True},
+                   "items": [{"description": "Café", "quantity": "1", "unit_price": "1000"}]}
+
+
+def datos(nombre: str) -> Any:
+    return json.loads((DATOS / nombre).read_text(encoding="utf-8"))
+
+
+class Respuesta:
+    def __init__(self, estado: int, cuerpo: Any = None, cabeceras: Optional[dict] = None, crudo: Optional[bytes] = None,
+                 tipo: str = "application/json"):
+        self.estado, self.cabeceras, self.tipo = estado, cabeceras or {}, tipo
+        self.crudo = crudo if crudo is not None else (b"" if cuerpo is None else json.dumps(cuerpo).encode("utf-8"))
+
+
+def json_(estado: int, cuerpo: Any, cabeceras: Optional[dict] = None) -> Respuesta:
+    return Respuesta(estado, cuerpo, cabeceras)
+
+
+def problema(estado: int, code: str, extra: Optional[dict] = None, cabeceras: Optional[dict] = None) -> Respuesta:
+    cuerpo = {"type": f"https://platform.trevol.si/docs/errores#{code}", "title": "Título", "status": estado, "code": code,
+              "retryable": False, "detail": f"Detalle de {code}", "request_id": "req_" + "c3" * 12, **(extra or {})}
+    return Respuesta(estado, cuerpo, cabeceras, tipo="application/problem+json")
+
+
+CORTAR = object()          # el servidor cierra la conexión sin responder (un fallo de red)
+
+
+class Servidor:
+    def __init__(self) -> None:
+        self.respuestas: list[Any] = []
+        self.peticiones: list[dict] = []
+        servidor = self
+
+        class Manejador(BaseHTTPRequestHandler):
+            protocol_version = "HTTP/1.1"
+
+            def log_message(self, *a: Any) -> None:
+                pass
+
+            def _atender(self) -> None:
+                largo = int(self.headers.get("content-length") or 0)
+                cuerpo = self.rfile.read(largo) if largo else b""
+                peticion = {"metodo": self.command, "ruta": self.path, "cabeceras": {k.lower(): v for k, v in self.headers.items()},
+                            "cuerpo": cuerpo.decode("utf-8", "replace")}
+                servidor.peticiones.append(peticion)
+                i = min(len(servidor.peticiones) - 1, len(servidor.respuestas) - 1)
+                r = servidor.respuestas[i]
+                r = r(peticion) if callable(r) else r          # una función recibe la petición y contesta según la ruta
+                if r is CORTAR:
+                    self.close_connection = True
+                    self.connection.close()
+                    return
+                self.send_response(r.estado)
+                self.send_header("Content-Type", r.tipo)
+                self.send_header("Content-Length", str(len(r.crudo)))
+                for k, v in r.cabeceras.items():
+                    self.send_header(k, v)
+                self.end_headers()
+                self.wfile.write(r.crudo)
+
+            do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = _atender
+
+        self._http = ThreadingHTTPServer(("127.0.0.1", 0), Manejador)
+        self._http.daemon_threads = True
+        self.url = f"http://127.0.0.1:{self._http.server_address[1]}/v1"
+        threading.Thread(target=lambda: self._http.serve_forever(poll_interval=0.01), daemon=True).start()
+
+    def cerrar(self) -> None:
+        self._http.shutdown()
+        self._http.server_close()
+
+    def vaciar(self, *respuestas: Any) -> "Servidor":
+        self.respuestas, self.peticiones = list(respuestas), []
+        return self
+
+
+@pytest.fixture()
+def servidor():
+    s = Servidor()
+    yield s
+    s.cerrar()
+
+
+class Banco:
+    """Un cliente contra el servidor falso, con las esperas anotadas (no se duerme) y el azar en 1 (factor 1,0)."""
+
+    def __init__(self, servidor: Servidor, *respuestas: Any, llave: str = LLAVE_TEST, **opciones: Any) -> None:
+        self.servidor = servidor.vaciar(*respuestas)
+        self.esperas: list[float] = []
+        self._n = 0
+
+        def uuid() -> str:
+            self._n += 1
+            return f"00000000-0000-4000-8000-{self._n:012d}"
+
+        self.trevol = Trevol(llave, base_url=servidor.url, _internos={"sleep": self.esperas.append, "random": lambda: 1.0, "uuid": uuid},
+                             **opciones)
+
+    @property
+    def peticiones(self) -> list[dict]:
+        return self.servidor.peticiones
+
+
+@pytest.fixture()
+def banco(servidor):
+    return lambda *r, **kw: Banco(servidor, *r, **kw)

trevol-0.1.0/pruebas/datos/errores.json

@@ -0,0 +1,33 @@
+{
+ "descripcion": "A mano (docs/api/43-sdks-y-documentacion.md §2.6.5). Cada code de Problem pertenece a una clase de error de los SDK; preparar.py falla si el enum de Problem tiene un code que no está aquí. Un code que el SDK no conoce (la API sumó uno) da la clase base, nunca rompe.",
+ "base": "TrevolError",
+ "clases": {
+  "AuthenticationError": ["authentication_required", "invalid_api_key"],
+  "PermissionDeniedError": ["permission_denied"],
+  "NotFoundError": ["not_found"],
+  "InvalidRequestError": ["method_not_allowed", "unsupported_version", "invalid_json", "invalid_request", "idempotency_key_required"],
+  "IdempotencyError": ["idempotency_key_reused"],
+  "ValidationError": ["validation_error"],
+  "ConflictError": ["external_id_in_use", "invalid_state", "duplicate_document", "request_in_progress", "previous_event_pending", "file_unavailable", "webhook_limit_reached"],
+  "PreconditionError": ["company_not_enabled", "numbering_unavailable", "certificate_problem", "tacit_acceptance_not_due"],
+  "DianRejectedError": ["dian_rejected"],
+  "BalanceError": ["insufficient_balance", "top_up_below_minimum", "top_up_above_maximum", "top_ups_unavailable"],
+  "RateLimitError": ["rate_limited"],
+  "DianUnavailableError": ["dian_unavailable"],
+  "InternalServerError": ["internal_error"]
+ },
+ "estados": {
+  "400": "InvalidRequestError",
+  "401": "AuthenticationError",
+  "402": "BalanceError",
+  "403": "PermissionDeniedError",
+  "404": "NotFoundError",
+  "409": "ConflictError",
+  "422": "ValidationError",
+  "429": "RateLimitError",
+  "5xx": "InternalServerError"
+ },
+ "sinRespuesta": "APIConnectionError",
+ "configuracion": "ConfigurationError",
+ "webhook": "WebhookVerificationError"
+}

trevol-0.1.0/pruebas/datos/eventos.json

@@ -0,0 +1,52 @@
+{
+ "balance.low": "BalanceEventData",
+ "certificate.expiring": "CertificateEventData",
+ "credit_note.accepted": "DocumentEventData",
+ "credit_note.delivered": "DocumentEventData",
+ "credit_note.email_bounced": "DocumentEventData",
+ "credit_note.email_failed": "DocumentEventData",
+ "credit_note.error": "DocumentEventData",
+ "credit_note.rejected": "DocumentEventData",
+ "debit_note.accepted": "DocumentEventData",
+ "debit_note.delivered": "DocumentEventData",
+ "debit_note.email_bounced": "DocumentEventData",
+ "debit_note.email_failed": "DocumentEventData",
+ "debit_note.error": "DocumentEventData",
+ "debit_note.rejected": "DocumentEventData",
+ "equivalent_document.accepted": "EquivalentDocumentEventData",
+ "equivalent_document.delivered": "EquivalentDocumentEventData",
+ "equivalent_document.email_bounced": "EquivalentDocumentEventData",
+ "equivalent_document.email_failed": "EquivalentDocumentEventData",
+ "equivalent_document.error": "EquivalentDocumentEventData",
+ "equivalent_document.rejected": "EquivalentDocumentEventData",
+ "equivalent_document_adjustment.accepted": "EquivalentDocumentEventData",
+ "equivalent_document_adjustment.delivered": "EquivalentDocumentEventData",
+ "equivalent_document_adjustment.email_bounced": "EquivalentDocumentEventData",
+ "equivalent_document_adjustment.email_failed": "EquivalentDocumentEventData",
+ "equivalent_document_adjustment.error": "EquivalentDocumentEventData",
+ "equivalent_document_adjustment.rejected": "EquivalentDocumentEventData",
+ "invoice.accepted": "DocumentEventData",
+ "invoice.delivered": "DocumentEventData",
+ "invoice.email_bounced": "DocumentEventData",
+ "invoice.email_failed": "DocumentEventData",
+ "invoice.error": "DocumentEventData",
+ "invoice.rejected": "DocumentEventData",
+ "numbering.expiring": "NumberingExpiringEventData",
+ "numbering.low": "NumberingLowEventData",
+ "payroll.accepted": "PayrollEventData",
+ "payroll.error": "PayrollEventData",
+ "payroll.rejected": "PayrollEventData",
+ "payroll_adjustment.accepted": "PayrollEventData",
+ "payroll_adjustment.error": "PayrollEventData",
+ "payroll_adjustment.rejected": "PayrollEventData",
+ "radian_event.accepted": "RadianEventData",
+ "radian_event.error": "RadianEventData",
+ "radian_event.rejected": "RadianEventData",
+ "support_document.accepted": "SupportDocumentEventData",
+ "support_document.error": "SupportDocumentEventData",
+ "support_document.rejected": "SupportDocumentEventData",
+ "support_document_adjustment.accepted": "SupportDocumentEventData",
+ "support_document_adjustment.error": "SupportDocumentEventData",
+ "support_document_adjustment.rejected": "SupportDocumentEventData",
+ "webhook.test": "TestEventData"
+}