libredte-lib-sdk 0.3.0__tar.gz → 0.5.0__tar.gz

libredte_lib_sdk-0.5.0/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"64edfb1a-a3db-44cc-af25-6c7405269fdf","pid":73057,"procStart":"Mon Sep  7 03:13:55 2026","acquiredAt":1789224889985}

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: libredte-lib-sdk
-Version: 0.3.0
+Version: 0.5.0
 Summary: SDK Python para la API de LibreDTE Lib (facturacion electronica de Chile).
 Project-URL: Homepage, https://www.libredte.cl
 Project-URL: Source, https://github.com/libredte/libredte-lib-sdk-python
@@ -133,16 +133,9 @@ Uso
     )
 
     # 3. Envío al SII (arma el sobre EnvioDTE y luego lo envía).
-    emisor = {
-        'rut': '76192083-9',
-        'razon_social': 'SASCO SpA',
-        'autorizacion_dte': {
-            'fecha_resolucion': '2014-08-22', 'numero_resolucion': 80,
-        },
-    }
-    sobre = b.document.dispatcher.create(
-        documento.xml_base64, certificate=certificate, emisor=emisor,
-    )
+    # `documento` ya trae certificate/emisor incluidos — no hace falta
+    # pasarlos aparte.
+    sobre = b.document.dispatcher.create(documento)
     envio = b.integration.sii_dte.send(
         sobre.xml_base64, certificate=certificate, company_rut='76192083-9',
     )
@@ -220,7 +213,7 @@ necesita para poblar sus propios datos, no operaciones de facturación.
     ejemplos = b.document.examples.list()  # [ExampleSummary(id=..., category=..., case=...), ...]
     ejemplo = b.document.examples.get(ejemplos[0].id)
     documento = b.document.builder.build_signed(
-        ejemplo.input_data, caf_xml=caf.xml_base64, certificate=certificate,
+        ejemplo.example, caf_xml=caf.xml_base64, certificate=certificate,
     )
 
     # Catálogos/repositorios reales (comunas, tipos de documento, etc.)
@@ -238,7 +231,7 @@ necesita para poblar sus propios datos, no operaciones de facturación.
     # ya extraídos en una sola llamada — mismo `Certificate` que usan
     # build_signed()/dispatcher.create(), ya con todos los datos.
     certificate = s.certificate.loader.load(datos_del_archivo_pfx, 'contraseña')
-    print(certificate.rut, certificate.nombre, certificate.email)
+    print(certificate.id, certificate.name, certificate.email)
 
 Errores
 -------

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/README.rst

@@ -89,16 +89,9 @@ Uso
     )
 
     # 3. Envío al SII (arma el sobre EnvioDTE y luego lo envía).
-    emisor = {
-        'rut': '76192083-9',
-        'razon_social': 'SASCO SpA',
-        'autorizacion_dte': {
-            'fecha_resolucion': '2014-08-22', 'numero_resolucion': 80,
-        },
-    }
-    sobre = b.document.dispatcher.create(
-        documento.xml_base64, certificate=certificate, emisor=emisor,
-    )
+    # `documento` ya trae certificate/emisor incluidos — no hace falta
+    # pasarlos aparte.
+    sobre = b.document.dispatcher.create(documento)
     envio = b.integration.sii_dte.send(
         sobre.xml_base64, certificate=certificate, company_rut='76192083-9',
     )
@@ -176,7 +169,7 @@ necesita para poblar sus propios datos, no operaciones de facturación.
     ejemplos = b.document.examples.list()  # [ExampleSummary(id=..., category=..., case=...), ...]
     ejemplo = b.document.examples.get(ejemplos[0].id)
     documento = b.document.builder.build_signed(
-        ejemplo.input_data, caf_xml=caf.xml_base64, certificate=certificate,
+        ejemplo.example, caf_xml=caf.xml_base64, certificate=certificate,
     )
 
     # Catálogos/repositorios reales (comunas, tipos de documento, etc.)
@@ -194,7 +187,7 @@ necesita para poblar sus propios datos, no operaciones de facturación.
     # ya extraídos en una sola llamada — mismo `Certificate` que usan
     # build_signed()/dispatcher.create(), ya con todos los datos.
     certificate = s.certificate.loader.load(datos_del_archivo_pfx, 'contraseña')
-    print(certificate.rut, certificate.nombre, certificate.email)
+    print(certificate.id, certificate.name, certificate.email)
 
 Errores
 -------

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/book/__init__.py

@@ -8,11 +8,10 @@ from __future__ import annotations
 from ...client import ApiClient
 from .builder import BookBuilderService
 from .loader import BookLoaderService
-from .models import Book, BookBag
+from .models import BookBag
 from .validator import BookValidatorService
 
 __all__ = [
-    'Book',
     'BookBag',
     'BookBuilderService',
     'BookComponent',

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/book/builder.py

@@ -9,7 +9,7 @@ from typing import Any
 
 from ...client import ApiClient
 from ..trading_parties.models import Certificate
-from .models import Book
+from .models import BookBag
 
 
 class BookBuilderService:
@@ -26,17 +26,19 @@ class BookBuilderService:
         bag: dict[str, Any],
         *,
         certificate: Certificate,
-    ) -> Book:
+    ) -> BookBag:
         """
         Construye el libro descrito por `bag`.
 
         `bag` trae `tipo` (`'libro_ventas'`, `'libro_compras'`,
         `'libro_boletas'`, `'libro_guias'`, `'resumen_ventas_diarias'`,
         sin tipar como enum cerrado), `caratula`, `detalle` y `emisor`,
-        tal cual el formato SII.
+        tal cual el formato SII. A diferencia de `BookLoaderService
+        .load()`, acá `BookBag.book` viene poblado (el libro construido
+        y firmado, con su `xml`).
         """
         data = self._client.call(
             self._BUILD_OPERATION,
             bag={**bag, 'certificate': certificate.to_payload()},
         )
-        return Book.from_api(data)
+        return BookBag.from_api(data)

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/book/loader.py

@@ -31,8 +31,8 @@ class BookLoaderService:
         Normaliza `caratula`/`detalle` de `bag` en un `BookBag`.
 
         `bag` trae `tipo`/`caratula`/`detalle`/`emisor`, tal cual el
-        formato SII. `BookBag.datos` siempre viene `None` (no construye
-        el libro); `BookBag.auth` viene poblado solo si
+        formato SII. `BookBag.book` siempre viene `None` (no construye
+        el libro); `BookBag.book_auth` viene poblado solo si
         `bag['emisor']` incluye `autorizacion_dte`.
         """
         data = self._client.call(

libredte_lib_sdk-0.5.0/libredte_lib_sdk/billing/book/models.py

@@ -0,0 +1,79 @@
+# Copyright (C) 2026 LibreDTE <https://www.libredte.cl>
+# SPDX-License-Identifier: MIT
+
+"""DTO del componente `billing.book`."""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from typing import Any, cast
+
+
+@dataclass(frozen=True, slots=True)
+class BookBag:
+    """
+    Bolsa de un libro tributario (`book.builder::build`/`book.loader::load`).
+
+    Ambas operaciones devuelven esta misma forma — la diferencia es qué
+    tan lejos llegó el procesamiento: `loader.load()` solo normaliza
+    `caratula`/`detalle` a partir de los datos de entrada (`book`
+    siempre viene `None`, sin importar el input); `builder.build()` sí
+    construye y firma el libro, por lo que `book` viene poblado (el
+    libro completo — genérico entre los 5 tipos, ej.
+    `libro_ventas`/`libro_compras` traen `{'LibroCompraVenta': {...}}`
+    junto a su `xml` en base64 — no se tipa más allá de `dict` porque
+    la clave raíz varía según el tipo). `book_auth` (la autorización
+    del emisor) solo viene poblada si esa autorización se incluyó junto
+    con los datos del emisor en la solicitud; si no, viene `None`.
+
+    `xml_base64`/`xml`/`xml_bytes` dan acceso directo al XML del libro
+    construido — solo válidos cuando `book` no es `None` (ver
+    `is_construido`); listos para encadenar a `BookValidatorService`.
+    No usa `XmlPayloadMixin`: acá `xml_base64` es una `@property` (el
+    libro puede no estar construido), no un campo simple.
+    """
+
+    book: dict[str, Any] | None
+    book_type: dict[str, Any]
+    book_auth: dict[str, Any] | None
+    caratula: dict[str, Any]
+    detalle: list[dict[str, Any]]
+    raw: dict[str, Any]
+
+    @property
+    def is_construido(self) -> bool:
+        """Si `book` viene poblado (`builder.build()`, no `loader.load()`)."""
+        return self.book is not None
+
+    @property
+    def xml_base64(self) -> str:
+        """XML del libro construido, en base64 — ver `BookValidatorService`."""
+        if self.book is None:
+            raise ValueError(
+                'Este BookBag no tiene un libro construido — viene de '
+                '`loader.load()`, no de `builder.build()`.',
+            )
+        return cast('str', self.book['xml'])
+
+    @property
+    def xml_bytes(self) -> bytes:
+        """XML del libro construido, decodificado desde base64."""
+        return base64.b64decode(self.xml_base64)
+
+    @property
+    def xml(self) -> str:
+        """XML del libro construido, como texto (ISO-8859-1)."""
+        return self.xml_bytes.decode('iso-8859-1')
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> BookBag:
+        """Construye un `BookBag` desde el `data` que devuelve la API."""
+        return cls(
+            book=data.get('book'),
+            book_type=data['book_type'],
+            book_auth=data.get('book_auth'),
+            caratula=data.get('caratula') or {},
+            detalle=data.get('detalle') or [],
+            raw=data,
+        )

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/common.py

@@ -15,6 +15,14 @@ class XmlPayloadMixin:
     Espera un atributo `xml_base64: str` en la clase concreta (`Document`,
     `DocumentEnvelope`, `Caf`, ...) y expone `xml_bytes`/`xml` sobre él,
     para no repetir esta misma conversión en cada DTO.
+
+    Solo para clases donde `xml_base64` es un campo real del dataclass
+    (siempre presente). `BookBag`/`DocumentBag` NO lo usan — su
+    `xml_base64` es una `@property` que puede lanzar (el XML puede no
+    existir aún, ej. un borrador sin construir) y un `@property` no
+    puede sobrescribir a un atributo simple heredado sin romper el
+    orden de campos del dataclass (`xml_base64` seguido de un campo
+    obligatorio) — definen `xml_bytes`/`xml` por su cuenta.
     """
 
     __slots__ = ()

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/document/__init__.py

@@ -11,7 +11,6 @@ from .dispatcher import DocumentDispatcherService
 from .examples import DocumentExamplesService
 from .loader import DocumentLoaderService
 from .models import (
-    Document,
     DocumentBag,
     DocumentEnvelope,
     Example,
@@ -23,7 +22,6 @@ from .renderer import DocumentRendererService
 from .validator import DocumentValidatorService
 
 __all__ = [
-    'Document',
     'DocumentBag',
     'DocumentBuilderService',
     'DocumentComponent',

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/document/builder.py

@@ -9,7 +9,7 @@ from typing import Any
 
 from ...client import ApiClient
 from ..trading_parties.models import Certificate
-from .models import Document
+from .models import DocumentBag
 
 
 class DocumentBuilderService:
@@ -33,27 +33,27 @@ class DocumentBuilderService:
         input_data: str | dict[str, Any],
         *,
         options: dict[str, Any] | None = None,
-    ) -> Document:
+    ) -> DocumentBag:
         """
         Emite el borrador de un DTE a partir de datos de entrada.
 
         `input_data` es el `Encabezado`/`Detalle` (y demás nodos) del
-        formato DTE del SII como `dict`, incluyendo
-        `Encabezado.IdDoc.Folio` (el SDK no asigna folios: eso lo decide
-        quien llama, típicamente porque lleva el correlativo) — o datos
-        en otro formato (XML/YAML, un formulario, etc.) junto con
+        formato DTE del SII como `dict` — o datos en otro formato
+        (XML/YAML, un formulario, etc.) junto con
         `options={'parser': {'strategy': '<estrategia>'}}` para indicar
         cómo parsearlos. Sin `options`, la API asume que `input_data` ya
-        viene en el formato DTE del SII (estrategia `default.json`). Sin
-        CAF ni certificado, el resultado no queda timbrado
-        (`Document.is_timbrado` es `False`).
+        viene en el formato DTE del SII (estrategia `default.json`).
+        `Encabezado.IdDoc.Folio` es opcional acá — un borrador sin folio
+        no falla (queda con folio `0` en `DocumentBag.document_id`, sin
+        nodo `Folio` en el XML). Sin CAF ni certificado, el resultado no
+        queda timbrado (`DocumentBag.is_timbrado` es `False`).
         """
         bag: dict[str, Any] = {'inputData': input_data}
         if options is not None:
             bag['options'] = options
 
         data = self._client.call(self._BUILD_OPERATION, bag=bag)
-        return Document.from_api(data)
+        return DocumentBag.from_api(data)
 
     def build_signed(
         self,
@@ -62,14 +62,16 @@ class DocumentBuilderService:
         options: dict[str, Any] | None = None,
         caf_xml: str,
         certificate: Certificate,
-    ) -> Document:
+    ) -> DocumentBag:
         """
         Genera el DTE real, timbrado y firmado.
 
-        `input_data`/`options` funcionan igual que en `build_draft()`.
-        Requiere un CAF real (XML tal como lo entrega el SII, cubriendo
-        el folio indicado en `input_data`) y el certificado digital del
-        emisor. Para pruebas, ambos se pueden generar con
+        `input_data`/`options` funcionan igual que en `build_draft()` —
+        acá sí se necesita un `Encabezado.IdDoc.Folio` real, cubierto
+        por `caf_xml` (el SDK no asigna folios: eso lo decide quien
+        llama, típicamente porque lleva el correlativo). Requiere un CAF
+        real (XML tal como lo entrega el SII) y el certificado digital
+        del emisor. Para pruebas, ambos se pueden generar con
         `IdentifierComponent.caf_faker` y
         `TradingPartiesComponent.mandatario_manager`.
         """
@@ -80,4 +82,4 @@ class DocumentBuilderService:
         bag['certificate'] = certificate.to_payload()
 
         data = self._client.call(self._BUILD_OPERATION, bag=bag)
-        return Document.from_api(data)
+        return DocumentBag.from_api(data)

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/document/dispatcher.py

@@ -5,17 +5,18 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from typing import Any, cast
 
 from ...client import ApiClient
-from ..trading_parties.models import Certificate
-from .models import DocumentEnvelope
+from .models import DocumentBag, DocumentEnvelope
 
 
 class DocumentDispatcherService:
     """Arma y valida el sobre `EnvioDTE` (`billing.document.dispatcher`)."""
 
     _CREATE_OPERATION = 'billing.document.dispatcher::create'
+    _CREATE_MANY_OPERATION = 'billing.document.dispatcher::createMany'
     _LOAD_XML_OPERATION = 'billing.document.dispatcher::loadXml'
     _VALIDATE_OPERATION = 'billing.document.dispatcher::validate'
     _VALIDATE_SCHEMA_OPERATION = 'billing.document.dispatcher::validateSchema'
@@ -27,42 +28,64 @@ class DocumentDispatcherService:
         """Guarda el `ApiClient` compartido usado para llamar a la API."""
         self._client = client
 
-    def create(
-        self,
-        document_xml_base64: str,
-        *,
-        certificate: Certificate,
-        emisor: dict[str, Any],
-    ) -> DocumentEnvelope:
+    def create(self, bag: DocumentBag) -> DocumentEnvelope:
         """
         Envuelve y firma un documento ya timbrado en un sobre `EnvioDTE`.
 
-        `document_xml_base64` es el XML en base64 del documento a
-        envolver — típicamente `Document.xml_base64` de un documento ya
-        timbrado y firmado (`DocumentBuilderService.build_signed`). El
-        sobre resultante es lo que se envía al SII (`SiiDteService.send`).
-
-        `emisor` es un `dict` con `rut`/`razon_social`/
-        `autorizacion_dte` (esta última con `fecha_resolucion`/
-        `numero_resolucion`), tal como lo espera la API.
+        `bag` es el `DocumentBag` ya timbrado y firmado que devuelve
+        `DocumentBuilderService.build_signed()` — trae `certificate`/
+        `emisor` incluidos, no hace falta pasarlos aparte. El sobre
+        resultante es lo que se envía al SII (`SiiDteService.send`).
         """
         data = self._client.call(
             self._CREATE_OPERATION,
-            bag={
-                'xmlDocument': document_xml_base64,
-                'certificate': certificate.to_payload(),
-                'emisor': emisor,
-            },
+            bag=self._bag_payload(bag),
         )
         return DocumentEnvelope.from_api(data)
 
+    def create_many(self, bags: Sequence[DocumentBag]) -> DocumentEnvelope:
+        """
+        Envuelve y firma 2+ documentos ya timbrados en un sobre `EnvioDTE`.
+
+        Igual que `create()`, pero para un sobre que agrupa más de un
+        documento — cada `DocumentBag` trae su propio `certificate`/
+        `emisor`. El sobre resultante queda firmado con el certificado
+        del PRIMER `DocumentBag` (el sobre en sí también se firma, no
+        solo cada documento).
+        """
+        data = self._client.call(
+            self._CREATE_MANY_OPERATION,
+            bags=[self._bag_payload(bag) for bag in bags],
+        )
+        return DocumentEnvelope.from_api(data)
+
+    @staticmethod
+    def _bag_payload(bag: DocumentBag) -> dict[str, Any]:
+        if bag.certificate is None:
+            raise ValueError(
+                'Este DocumentBag no tiene certificado — ¿se firmó con '
+                '`builder.build_signed()`?',
+            )
+        if bag.emisor is None:
+            raise ValueError(
+                'Este DocumentBag no tiene emisor — ¿se construyó con '
+                '`builder.build_draft/build_signed()` o se cargó con '
+                '`loader.load_xml()`?',
+            )
+        return {
+            'xmlDocument': bag.xml_base64,
+            'certificate': bag.certificate.to_payload(),
+            'emisor': bag.emisor,
+        }
+
     def load_xml(self, xml_base64: str) -> DocumentEnvelope:
         """
         Carga un sobre `EnvioDTE` ya existente desde su XML (base64).
 
-        Caso de uso típico: reprocesar un sobre ya guardado, o normalizar
-        un DTE suelto recibido de un tercero (la API arma un sobre nuevo
-        a partir de él).
+        El `DocumentEnvelope` resultante trae en `documents` una bolsa
+        por cada documento tributario que el sobre agrupaba — uno o
+        más — y en `caratula` los datos de la carátula ya presente en
+        ese XML.
         """
         data = self._client.call(self._LOAD_XML_OPERATION, xml=xml_base64)
         return DocumentEnvelope.from_api(data)

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/document/examples.py

@@ -17,7 +17,7 @@ class DocumentExamplesService:
     de `libredte-lib-core` (`tests/fixtures/yaml/documentos_ok/`) — uno
     por variante de negocio real (descuentos, impuesto adicional, pago a
     crédito, exportación, etc.), no datos inventados por el SDK.
-    `Example.input_data` de `get()` se le pasa tal cual a
+    `Example.example` de `get()` se le pasa tal cual a
     `DocumentBuilderService.build_draft()`/`.build_signed()`, típicamente
     reemplazando `Encabezado.IdDoc.Folio` y `Encabezado.Receptor` por los
     propios de quien usa el SDK antes de construir el documento.

{libredte_lib_sdk-0.3.0 → libredte_lib_sdk-0.5.0}/libredte_lib_sdk/billing/document/loader.py

@@ -26,6 +26,13 @@ class DocumentLoaderService:
         self._client = client
 
     def load_xml(self, xml_base64: str) -> DocumentBag:
-        """Carga y normaliza el documento cuyo XML (base64) es `xml_base64`."""
+        """
+        Carga y normaliza el documento cuyo XML (base64) es `xml_base64`.
+
+        Devuelve la misma `DocumentBag` que `DocumentBuilderService` —
+        `document_id`/`xml_base64` reconstruyen lo que ya se le pasó
+        acá, `document`/`document_type`/`document_stamp_base64`/etc.
+        son el valor agregado real: los datos ya normalizados.
+        """
         data = self._client.call(self._LOAD_XML_OPERATION, xml=xml_base64)
         return DocumentBag.from_api(data)