libredte-lib-sdk 0.1.0__tar.gz

libredte_lib_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  tests:
+    name: Tests
+    timeout-minutes: 10
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ['3.14']
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Display Python version
+        run: python --version
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: Run Ruff (lint)
+        run: ruff check .
+
+      - name: Run Ruff (format)
+        run: ruff format --check .
+
+      # No corre los tests `live` (marker `live`, excluidos por defecto vía
+      # `addopts` en pyproject.toml): golpean la API real de LibreDTE y/o
+      # un ambiente de desarrollo local, no algo apto para CI.
+      - name: Run pytest
+        run: |
+          mkdir -p var
+          pytest -v \
+            --junitxml=var/tests-results.xml \
+            --cov=libredte_lib_sdk \
+            --cov-report=xml:var/tests-coverage.xml
+
+      - name: Upload pytest result report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tests-results-python_${{ matrix.python-version }}.xml
+          path: var/tests-results.xml
+
+      - name: Upload Coverage Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: tests-coverage-python_${{ matrix.python-version }}.xml
+          path: var/tests-coverage.xml

libredte_lib_sdk-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python.
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.coverage
+var/
+
+# Archivos específicos del sistema operativo.
+.DS_Store

libredte_lib_sdk-0.1.0/CLAUDE.md

@@ -0,0 +1,482 @@
+# `libredte_lib_sdk` — plan y bitácora
+
+> Este archivo es la fuente de verdad del diseño. Si una sesión de chat se
+> corta, léelo primero: acá está el porqué de cada decisión, no solo el qué.
+
+## Objetivo
+
+SDK Python (`libredte_lib_sdk`) que orquesta la **API** de LibreDTE Lib
+(por defecto `https://core.libredte.cl/api`, spec en
+`/api/openapi-docs.json`) para cubrir 5 operaciones de negocio sobre DTE
+chilenos:
+
+1. Emitir el **borrador** de un DTE.
+2. Generar el DTE real, **timbrado y firmado**.
+3. **Enviar** el DTE al SII.
+4. Obtener el **estado** de un envío al SII por su **Track ID**.
+5. Generar el **PDF** (o HTML) de un DTE (borrador o emitido).
+
+Más 4 operaciones de soporte para el CAF y el certificado — 2 para poder
+probar los 5 flujos de punta a punta sin credenciales reales, y 2 para
+poder usar un CAF **real** en producción (no solo ficticio):
+
+6. Generar un **CAF ficticio** (`billing.identifier.caf_faker`).
+7. Generar un **certificado digital ficticio** (`billing.trading_parties
+   .mandatario_manager::createFakeCertificate`).
+8. **Cargar un CAF real** desde su XML (`billing.identifier.caf_loader`).
+9. **Validar un CAF** — vigencia, firma (`billing.identifier
+   .caf_validator`).
+
+Este SDK es la capa de "lógica de negocio / orquestación DTE" para un
+ecosistema donde una app Django, más adelante, será *solo* vista + auth +
+persistencia. Toda la lógica de facturación electrónica vive acá. Por lo
+tanto: **API estable, servicios explícitos, sin acoplar a Django ni a
+ningún framework web**.
+
+### Relación con `libredte-lib-core-bridge-python`
+
+Referencia de diseño (no dependencia):
+`/Users/delaf/dev/docker-python3.14-caddy-server/sites/_bridge-libredte/libredte-lib-core-bridge-python`.
+
+Ese paquete llama al *mismo* código PHP (`libredte-lib-core`) pero vía
+`phpy` (embebido, dentro de un contenedor especial). Acá se llama al
+*mismo* código, pero vía HTTP a la API pública. Por eso la convención de
+nombres de operación es idéntica: `paquete.componente.worker::operacion`
+(ej. `billing.document.builder::build`), y la API la expone 1:1 como
+`POST /{paquete}/{componente}/{worker}/{operacion}`.
+
+**No es una API REST**, aunque el proyecto la llamó así al principio —
+corregido a pedido del usuario. Todo pasa por `POST`, sin distinción de
+verbos HTTP por semántica (crear/leer/validar todas usan `POST`), y las
+rutas son RPC (`paquete/componente/worker/operacion`, un identificador
+de operación, no un recurso). Es más precisa llamarla "API HTTP" o "API
+RPC sobre HTTP" — así se la llama en el resto de este archivo, en el
+código y en `README.rst`.
+
+## `core.libredte.cl` vs `pro.libredte.cl`
+
+El SDK apunta por defecto a **`core.libredte.cl`** (decisión explícita
+del usuario — hubo una pasada previa apuntando a `pro.libredte.cl` por
+defecto, revertida). Ambas exponen el mismo contrato (mismo
+`openapi-docs.json`, mismos paths `billing/*`, mismo formato de
+respuesta); se diferencian en el límite de solicitudes:
+`core.libredte.cl` limita a 50 cada 24 horas (header
+`x-ratelimit-limit`), `pro.libredte.cl` a ~3600/hora — y trae además
+paquetes adicionales (`human_resources`) fuera de alcance de este SDK.
+
+`LIBREDTE_LIB_SDK_BASE_URL`/`base_url` está documentado como opción pública
+en `README.rst` — cambiar el default en el futuro es una decisión de
+producto, no algo a inferir de este archivo.
+
+Sigue siendo configurable (`LibreDTE(base_url=...)` o env var
+`LIBREDTE_LIB_SDK_BASE_URL`) por si hace falta apuntar a `core` u otro
+ambiente. `ApiClient` controla el caso de límite excedido: si la API
+responde `429`, se levanta `LibreDteRateLimitError` (subclase de
+`LibreDteApiError`) con `.retry_after`/`.limit`/`.remaining` leídos de los
+headers `Retry-After`/`X-RateLimit-Limit`/`X-RateLimit-Remaining`. No se
+pudo reproducir un `429` real en vivo (habría implicado agotar la cuota
+real de un ambiente compartido, sin ningún beneficio de diseño) — la
+implementación sigue el status code HTTP estándar más los headers que la
+propia API ya expone de forma consistente en toda respuesta.
+
+## Decisiones de diseño (YAGNI / KISS / SRP)
+
+- **No reimplementar el esquema DTE del SII en Python.** Los datos de
+  `Encabezado`/`Detalle`/etc. (`parsedData`) se pasan como `dict` tal cual
+  el formato SII — la validación real la hace `libredte-lib-core` en el
+  servidor.
+- **DTO solo donde el SDK aporta valor**: contenedores tipados + conversión
+  de/hacia el payload JSON de la API (nombres de campo, base64 de XML).
+- **Un servicio por worker de la API**, no por operación — mismo criterio
+  de SRP que usa la API misma.
+- **La estructura de paquetes Python espeja la de la API**:
+  `billing.{document,identifier,trading_parties,integration}`, cada
+  componente con un `*Component` que agrupa sus servicios por worker (ver
+  "Estructura del módulo" abajo). Esto se decidió explícitamente en esta
+  segunda pasada (con autorización para crear submódulos): con la API
+  exponiendo más de 40 operaciones a través de 7 componentes (y otro
+  paquete completo, `human_resources`, en `pro.libredte.cl`), un único
+  módulo plano ya no escala — un paquete/componente nuevo es un
+  directorio nuevo, no tocar nada existente.
+- **Solo síncrono**, sin `pydantic`, cliente HTTP genérico y delgado,
+  errores tipados sin sobre-modelar por código HTTP — mismos argumentos
+  que en la primera pasada, sin cambios.
+- **`httpx`** como única dependencia de runtime.
+
+## Estructura del módulo
+
+```
+libredte_lib_sdk/
+├── __init__.py          # exports públicos (re-exporta todo lo de billing/*)
+├── py.typed
+├── client.py              # ApiClient: operation_id -> URL, JSON/binario, rate limit
+├── exceptions.py            # LibreDteSdkError, LibreDteApiError (+RateLimit), ConnectionError
+├── sdk.py                     # LibreDTE: fachada única -> sdk.billing.*
+└── billing/                    # paquete "billing" de la API
+    ├── __init__.py                # BillingPackage: agrupa los componentes
+    ├── common.py                    # XmlPayloadMixin (xml_bytes/xml compartido)
+    ├── enums.py                      # SiiEnvironment
+    ├── document/                      # componente "document"
+    │   ├── __init__.py                  # DocumentComponent
+    │   ├── models.py                      # AutorizacionDte, Emisor, Document, Envelope, RenderResult, Rendering
+    │   ├── builder.py                       # DocumentBuilderService (build_draft/build_signed)
+    │   ├── dispatcher.py                      # DocumentDispatcherService (create -> sobre EnvioDTE)
+    │   └── renderer.py                          # DocumentRendererService (render -> RenderResult)
+    ├── identifier/                    # componente "identifier"
+    │   ├── __init__.py                  # IdentifierComponent
+    │   ├── models.py                      # Caf
+    │   ├── caf_faker.py                     # CafFakerService (create, ficticio)
+    │   ├── caf_loader.py                      # CafLoaderService (load, real)
+    │   └── caf_validator.py                     # CafValidatorService (validate)
+    ├── trading_parties/               # componente "trading_parties"
+    │   ├── __init__.py                  # TradingPartiesComponent
+    │   ├── models.py                      # Certificate
+    │   └── mandatario_manager.py            # MandatarioManagerService (create_fake_certificate)
+    └── integration/                   # componente "integration"
+        ├── __init__.py                  # IntegrationComponent
+        ├── models.py                      # SendResult, SiiStatus
+        └── sii_dte.py                       # SiiDteService (send/check_status)
+```
+
+Extensible por diseño: agregar un worker nuevo de un componente ya
+soportado es un archivo nuevo + una línea en el `__init__.py` de ese
+componente. Agregar un componente nuevo (o el paquete `human_resources`
+completo) es un subpaquete nuevo + una línea en `billing/__init__.py` (o
+en `sdk.py` para un paquete nuevo) — nada existente se toca.
+
+Los 5 flujos de negocio pedidos, más los 2 fakers, mapeados:
+
+```python
+sdk = LibreDTE()
+b = sdk.billing
+
+# Fakers (solo para pruebas) o CAF real (producción):
+caf = b.identifier.caf_faker.create(emisor_dict, codigo_documento=33)
+# caf = b.identifier.caf_loader.load(xml_base64_subido_por_el_usuario)
+# b.identifier.caf_validator.validate(caf.xml_base64)  # opcional, valida antes de usarlo
+certificate = b.trading_parties.mandatario_manager.create_fake_certificate(
+    mandatario_dict,
+)
+
+# 1. Borrador.
+borrador = b.document.builder.build_draft(parsed_data)
+
+# 2. Timbrado y firmado.
+documento = b.document.builder.build_signed(
+    parsed_data, caf_xml=caf.xml_base64, certificate=certificate,
+)
+
+# 3. Enviar al SII (arma el sobre EnvioDTE y luego lo envía).
+sobre = b.document.dispatcher.create(
+    documento.xml_base64, certificate=certificate, emisor=emisor_dto,
+)
+envio = b.integration.sii_dte.send(
+    sobre.xml_base64, certificate=certificate, company_rut=rut,
+)
+
+# 4. Estado por Track ID.
+estado = b.integration.sii_dte.check_status(
+    envio.track_id, certificate=certificate, company_rut=rut,
+)
+
+# 5. HTML o PDF — misma forma de respuesta para ambos (ver más abajo).
+html = b.document.renderer.render(documento.xml_base64, format='html').first
+pdf = b.document.renderer.render(documento.xml_base64, format='pdf').first
+pdf_bytes = pdf.content_bytes
+```
+
+## Verificación en vivo (contra `pro.libredte.cl`, con datos ficticios)
+
+Toda la cadena se ejecutó de punta a punta usando el SDK real (no
+curl/urllib) contra la API real, sin mocks:
+
+| Paso | Resultado |
+|---|---|
+| `caf_faker.create(...)` | OK — CAF ficticio real, XML válido. |
+| `mandatario_manager.create_fake_certificate(...)` | OK — certificado autofirmado real (CA de prueba "Derafu Test Certificate Authority"). |
+| `builder.build_draft(...)` | OK — borrador, `is_timbrado == False`. |
+| `builder.build_signed(...)` (con el CAF y certificado ficticios) | OK — documento con TED real, `is_timbrado == True`. |
+| `dispatcher.create(...)` | OK — sobre `EnvioDTE` real y válido. |
+| `sii_dte.send(...)` | **Falla, como es esperable**: el SII real (ambiente de certificación) rechaza el certificado ficticio con `AuthenticateException` ("XML Inválido, elemento «Certificate» no existe") — el SII realmente recibió y evaluó la solicitud, y la rechazó por autenticación, no por un error del SDK. Se propaga como `LibreDteApiError` normal, con `.php_class` identificando la excepción real. |
+| `sii_dte.check_status(...)` | Mismo rechazo por autenticación (con un Track ID inventado, ya que no hay uno real posible sin autenticación exitosa). |
+| `renderer.render(..., format='html')` | OK — HTML real del documento, con timbre. |
+| `renderer.render(..., format='pdf')` | **OK** (ver "Render de PDF: bug y fix" abajo) — PDF real, válido, verificado con `file` (`PDF document, version 1.4, 1 pages`). Requiere una API con el fix del render desplegado (ver esa sección: hoy solo confirmado contra un ambiente de desarrollo local, no contra `pro.libredte.cl` pública). |
+
+Esto confirma: el diseño de servicios/DTO es correcto, y el manejo de
+errores de la API funciona (tanto para rechazos de negocio como de
+autenticación real del SII).
+
+Durante la primera verificación (contra el shape viejo de `render`) se
+encontró y corrigió un bug real del SDK: `DocumentRendererService
+.render()` asumía que cualquier respuesta no-bytes podía convertirse con
+`bytes(result)` — pero para formatos de texto (ej. `html`, en el shape
+viejo) la API devolvía un `string` dentro del sobre JSON, y `bytes(str)`
+sin encoding explícito lanza `TypeError`. Quedó resuelto de raíz al
+migrar al shape nuevo (`render()` ahora siempre decodifica base64 desde
+`Rendering.content_base64`, sin ninguna rama `str`/`bytes` especial) —
+ver "Render de PDF: bug y fix" abajo.
+
+## Render de PDF: bug y fix
+
+### El bug (histórico)
+
+`POST /billing/document/renderer/render` con `options.renderer.format` en
+cualquier formato **binario** (`pdf`) devolvía siempre `500`:
+
+```
+Derafu\Http\Response::asText(): Argument #1 ($data) must be of type
+string, array given, called in
+.../vendor/derafu/http/src/Middleware/ResponseNormalizerMiddleware.php
+on line 108
+```
+
+Reproducible en `core.libredte.cl` y `pro.libredte.cl`, con cualquier
+documento/opciones/headers — no era nada influenciable desde el cliente
+(se descartó exhaustivamente: tipo de documento, timbrado o no, claves
+extra en `options.renderer`, headers `Accept`). El motivo: la API
+devolvía el binario como una respuesta HTTP cruda, fuera del sobre JSON
+`{meta, data}` habitual — y esa rama especial de la capa HTTP
+(`derafu/http`, `ResponseNormalizerMiddleware`) estaba rota.
+`format='html'` (que sí iba dentro del sobre JSON normal, como `string`)
+funcionaba bien — la pista de que el problema era justo esa rama binaria
+"cruda", no el renderer de DTE en sí.
+
+### El fix
+
+La recomendación (dada en esta misma sesión, antes de que el usuario
+mostrara el fix): que `render` **siempre** devuelva su resultado dentro
+del sobre JSON de siempre, en base64 — el mismo patrón que ya usa el
+resto de la API (XML de documentos, sobres, CAF) — en vez de una rama
+especial para contenido binario. Es exactamente lo que se implementó, con
+un plus: soporte para **múltiples archivos por llamada** (copias
+tributarias/cedibles). Shape nuevo, confirmado en vivo:
+
+```json
+{
+  "meta": {"timestamp": ..., "data_type": "...RenderResult"},
+  "data": {
+    "renderings": [
+      {
+        "content": "<base64>",
+        "mimeType": "application/pdf",
+        "filename": "LibreDTE_76192083-9_T033F000000000001_tributaria.pdf",
+        "label": "tributaria",
+        "copies": 1,
+        "copyNumber": 1
+      }
+    ]
+  }
+}
+```
+
+**Verificado en vivo, con el SDK real, contra un ambiente de desarrollo
+local (`http://localhost:9000/api`)**: `render(..., format='pdf').first
+.content_bytes` produce un PDF real y válido — confirmado con `file`
+(`PDF document, version 1.4, 1 pages`), generado a partir de un documento
+timbrado y firmado con CAF y certificado ficticios (`caf_faker`/
+`mandatario_manager.create_fake_certificate`).
+
+### Copias múltiples (`renderings`)
+
+Agregado en una segunda vuelta sobre el mismo endpoint: `bag.options
+.renderer.renderings` (`dict[str, int]`, ej. `{'tributaria': 2,
+'cedible': 1}`) pide una o más presentaciones, y una o más copias de
+cada una, en la misma llamada. Sin esa clave, la API genera una única
+copia `'tributaria'` (default). `Rendering` ahora trae `label` (qué
+presentación es), `copies` (cuántas se pidieron de ese label) y
+`copy_number` (cuál de esas copias es esta, 1-indexado) — necesarios
+para poder distinguir entre varios ítems de `renderings` cuando se pide
+más de uno. `RenderResult.by_label(label)` filtra por presentación.
+
+Reglas de negocio confirmadas en vivo contra `localhost:9000` (worker
+`billing.document.renderer`, mismo endpoint, sin cambios de ruta):
+
+- Presentación inexistente (ej. `'noexiste'`) → `LibreDteApiError` 500,
+  `RendererException`, `detail` contiene `"no existe"`.
+- Presentación que la API no puede generar para ese tipo de documento
+  (ej. `'cedible'` — copia cedible/acuse de recibo — en una boleta, que
+  no lo admite) **se omite en silencio** si se pidió junto con al menos
+  una que sí se pudo generar: `renderings={'tributaria': 1, 'cedible':
+  1}` en una boleta devuelve solo la `'tributaria'`, sin error.
+- Si **ninguna** de las presentaciones pedidas se pudo generar (ej.
+  pedir *solo* `'cedible'` para una boleta) → `LibreDteApiError` 500,
+  `RendererException`, `detail` distinto ("no fue posible generar
+  ninguna...").
+
+El SDK no modela `'tributaria'`/`'cedible'` como un enum cerrado: son
+strings que la propia API valida (y da un error claro si no reconoce
+uno) — hardcodear los valores conocidos hoy sería asumir que no van a
+agregar un tercero mañana.
+
+### Ojo: esto puede no estar desplegado en la API pública todavía
+
+Al momento de escribir esto, este contrato (`renderings` incluido) se
+confirmó únicamente en el ambiente de desarrollo local del usuario
+(`http://localhost:9000/api`) — `pro.libredte.cl`/`core.libredte.cl` (la
+API pública) seguían con el shape viejo (y el 500 para `pdf`) la última
+vez que se probaron. El SDK **solo** soporta el shape nuevo
+(`data.renderings[]`) — no hay compatibilidad con el shape viejo. Si la
+API contra la que apunta `LibreDTE()` (default: `core.libredte.cl`)
+todavía no tiene el fix desplegado, `render()` va a fallar
+(`TypeError`/`KeyError`, según qué tan viejo sea el shape que devuelva)
+— no es un bug del SDK, es esa API sin actualizar todavía.
+
+### Cómo probar el render localmente
+
+```bash
+make install-dev
+
+# Contra la API pública (default: core.libredte.cl):
+.venv/bin/pytest -m live -v tests/integration/test_document_rendering.py
+
+# Contra un ambiente propio con el fix ya desplegado:
+LIBREDTE_LIB_SDK_BASE_URL=http://localhost:9000/api .venv/bin/pytest \
+    -m live -v tests/integration/test_document_rendering.py
+```
+
+8 tests, todos verdes contra `localhost:9000` (confirmado en esta
+sesión): formato HTML, formato PDF, default (una copia tributaria),
+varias presentaciones en una llamada, varias copias de una misma
+presentación, omisión silenciosa de una presentación no soportada,
+presentación inexistente, y "ninguna presentación pudo generarse".
+
+## Otros supuestos no verificados en vivo
+
+- **`SendResult.track_id`** y **`SiiStatus.status`**: la respuesta
+  exitosa real de `sendXmlDocument`/`checkXmlDocumentSentStatus` nunca se
+  pudo observar (el SII rechaza la autenticación antes de llegar a un
+  200, con cualquier certificado que no sea uno real emitido para un RUT
+  real — ver tabla de verificación arriba). Los nombres de campo
+  (`trackId`/`track_id`, `status`/`estado`/`state`) siguen siendo el
+  mejor supuesto según la convención de nombres del resto de la API, con
+  fallback defensivo y `.raw` como fuente de verdad completa. Esto solo
+  se puede cerrar con un certificado real emitido para un RUT real con
+  folios autorizados de verdad — fuera de alcance de este SDK/sesión.
+- `environment`: `0` = certificación, `1` = producción — convención
+  estándar del ecosistema LibreDTE, coherente con lo observado (se probó
+  contra `environment: 0` y efectivamente habló con el SII de
+  certificación).
+
+## Cobertura de la API: qué está mapeado y qué falta
+
+`http://localhost:9000/api/openapi-docs.json` expone hoy 39 operaciones
+(todas bajo el paquete `billing`; no se detectó `human_resources` en este
+ambiente local, a diferencia de `pro.libredte.cl`). El SDK mapea 9:
+
+| Worker (componente) | Operación | ¿En el SDK? |
+|---|---|---|
+| `document.builder` | `build` | ✅ `DocumentBuilderService.build_draft`/`build_signed` |
+| `document.dispatcher` | `create` | ✅ `DocumentDispatcherService.create` |
+| `document.renderer` | `render` | ✅ `DocumentRendererService.render` |
+| `identifier.caf_faker` | `create` | ✅ `CafFakerService.create` |
+| `identifier.caf_loader` | `load` | ✅ `CafLoaderService.load` |
+| `identifier.caf_validator` | `validate` | ✅ `CafValidatorService.validate` |
+| `trading_parties.mandatario_manager` | `createFakeCertificate` | ✅ `MandatarioManagerService.create_fake_certificate` |
+| `integration.sii_dte` | `sendXmlDocument` | ✅ `SiiDteService.send` |
+| `integration.sii_dte` | `checkXmlDocumentSentStatus` | ✅ `SiiDteService.check_status` |
+
+`caf_loader`/`caf_validator` se agregaron en esta misma sesión (decisión
+del usuario: cerrar la única brecha real dentro de lo ya acordado antes
+de pasar a la app Django — ver "Estado"). Verificado en vivo el flujo
+completo con un CAF **no ficticio** en el sentido de "cargado, no
+generado" (`caf_faker::create` → `caf_loader::load` de ese mismo XML →
+`caf_validator::validate` → `build_signed()`), simulando cómo lo haría
+la app Django con un CAF real subido por el usuario.
+
+Detalle no obvio del contrato, confirmado en vivo: `caf_validator
+::validate` espera el **XML en base64** (el mismo dato que
+`caf_loader::load`), no la entidad `Caf` completa como `dict` — pasar el
+`dict` da 422 ("requires string data"), aunque el parámetro de la
+operación se llame `caf` y no `xml`.
+
+Las 30 restantes, agrupadas por lo que aportarían a una app de
+facturación (emisión), con mi recomendación de prioridad:
+
+**Expanden a un caso de uso legítimo pero nuevo (no estaba en el pedido
+original) — evaluaría agregar recién cuando la app Django los necesite,
+no antes:**
+
+| Worker | Operaciones | Qué habilitan |
+|---|---|---|
+| `document.validator` | `validate`, `validateSchema`, `validateSignature` | Validar los datos de un documento *antes* de construirlo — feedback de UI más temprano/claro que esperar el error de `builder.build`. |
+| `document.dispatcher` | `loadXml`, `validate`, `validateSchema`, `validateSignature` | Cargar/validar un sobre `EnvioDTE` ya existente (ej. reprocesar uno guardado). |
+| `document.loader` | `loadXml` | Cargar un documento individual desde su XML (ej. reconstruir datos desde un DTE ya emitido). |
+| `trading_parties.mandatario_manager` | `createFromCertificate` | Extraer RUT/nombre/email desde un certificado **real** subido por el usuario — útil para mostrar "certificado de Juan Pérez, vence en X días" en la futura UI. |
+| `integration.sii_dte` | `validateDocument`, `validateDocumentSignature` | Confirmar que un documento ya enviado quedó aceptado en el SII (reconciliación), independiente de `checkXmlDocumentSentStatus`. |
+| `integration.sii_dte` | `requestXmlDocumentSentStatusByEmail` | Pedirle al SII que mande el estado por correo — alternativa a consultar, uso más bien excepcional. |
+
+**Son un dominio de negocio distinto — "recibir" documentos de
+proveedores (compras) y libros contables mensuales, no "emitir" (ventas)
+— agregaría solo si la app Django va a cubrir eso, es una decisión de
+alcance, no una omisión:**
+
+| Componente | Qué es |
+|---|---|
+| `integration.sii_rcv` (`checkDocumentAssignability`, `getDocumentSiiReceptionDate`, `listDocumentEvents`, `submitDocumentAcceptance`) | Registro de Compra y Venta del SII: aceptar/reclamar un DTE recibido de un proveedor, consultar su historial — esto es el lado "recibo facturas de otros", no "emito facturas". |
+| `exchange.*` (`document_response`, `receiver`, `sender`) | Intercambio de documentos entre partes (acuses de recibo, envío/recepción P2P) — mismo dominio de "recepción" que lo anterior. |
+| `book.*` (`builder`, `loader`, `validator`) | Libros de Ventas/Compras/Boletas/Guías y Resumen de Ventas Diarias — obligación periódica del SII, capacidad grande y separada de emitir un DTE puntual. |
+| `ownership_transfer.aec` + `integration.sii_rtc` | Cesión electrónica de créditos (factoring) — nicho, solo si la app va a soportar factoring. |
+
+## Estado
+
+- [x] Investigación del spec + requests reales contra ambas APIs
+      (`core`/`pro`).
+- [x] `CLAUDE.md` (este archivo).
+- [x] Paquete reorganizado en `billing/{document,identifier,
+      trading_parties,integration}`, con un `*Component`/`*Service` por
+      worker de la API.
+- [x] Fakers agregados como servicios del SDK (`caf_faker`,
+      `mandatario_manager.create_fake_certificate`).
+- [x] Manejo de rate limit (`LibreDteRateLimitError` en `429`).
+- [x] Tests unitarios (mock de HTTP con `respx`, sin red real): 35 tests,
+      todos verdes (`make test`).
+- [x] Tests de integración en vivo, marcados `live`, excluidos por
+      defecto: 12 tests, todos verdes (`make test-live`, ambiente propio).
+- [x] Verificación end-to-end contra la API real de los 5 flujos + los 2
+      fakers, con el SDK real (no curl) — ver tabla arriba.
+- [x] Render de PDF: bug reportado, fix diseñado en conjunto, verificado
+      en vivo (PDF real y válido) contra el ambiente de desarrollo del
+      usuario. Ver "Render de PDF: bug y fix" arriba.
+- [x] Copias múltiples (`renderings`): agregado por la API, soportado en
+      el SDK (`render(..., renderings={...})`, `Rendering.label/copies
+      /copy_number`, `RenderResult.by_label()`), con los 4 casos de
+      negocio (varias presentaciones, varias copias, omisión silenciosa,
+      presentación inexistente, ninguna generable) verificados en vivo.
+- [ ] **El fix/las funcionalidades de render todavía no están
+      desplegadas en la API pública** (`pro.libredte.cl`/
+      `core.libredte.cl`) — solo confirmado contra
+      `http://localhost:9000/api`. `LibreDTE()` sin `base_url` explícito
+      seguirá fallando en `render()` hasta que se despliegue ahí. No es
+      un TODO del SDK — es un TODO de seguimiento del despliegue.
+- [ ] Cerrar los supuestos de `SendResult`/`SiiStatus` con un certificado
+      real (fuera de alcance de este SDK/sesión).
+- [x] **`identifier.caf_loader::load` + `identifier.caf_validator
+      ::validate`**: agregados (decisión del usuario, tras evaluar el
+      mapeo completo de cobertura de la API — ver esa sección arriba).
+      Cierra la única brecha real que quedaba dentro de los 5 flujos ya
+      acordados: ahora sí se puede timbrar con un CAF **real** (cargado,
+      no ficticio) en producción. Verificado en vivo de punta a punta
+      (`caf_faker` → `caf_loader.load` de ese XML → `caf_validator
+      .validate` → `build_signed()` con ese CAF cargado).
+- [ ] **Siguiente paso decidido**: pasar a la app Django, en su propio
+      repo. El resto de las 30 operaciones que faltan (ver "Cobertura de
+      la API") queda para agregar cuando la app Django las necesite de
+      verdad, no antes — decisión explícita del usuario, no un olvido.
+
+## Desarrollo
+
+```bash
+make install-dev
+make check       # ruff (lint + format --check) + tests unitarios (offline)
+make test-live   # tests de integración reales contra la API (red)
+```
+
+## CI
+
+`.github/workflows/ci.yml` — `workflow_dispatch` + `push`/`pull_request`
+sobre `main`, un solo job (`ruff check`, `ruff format --check`, `pytest`
+con reporte JUnit + cobertura como artifacts), Python 3.14. Mismo patrón
+que `derafu/derafu-backbone` (PHP), adaptado a Python/`pyproject.toml`.
+Corre **solo** los tests unitarios (offline, sin red) — los `live`
+(marker `live`) quedan fuera por diseño: dependen de la API real y/o de
+un ambiente de desarrollo local (`localhost:9000`) que no existe en CI.