libredte-lib-sdk 0.1.0__py3-none-any.whl

libredte_lib_sdk/__init__.py

@@ -0,0 +1,75 @@
+"""SDK Python para la API de LibreDTE Lib (facturación electrónica Chile)."""
+
+from .billing import BillingPackage
+from .billing.document import (
+    AutorizacionDte,
+    Document,
+    DocumentBuilderService,
+    DocumentComponent,
+    DocumentDispatcherService,
+    DocumentRendererService,
+    Emisor,
+    Envelope,
+    Rendering,
+    RenderResult,
+)
+from .billing.enums import SiiEnvironment
+from .billing.identifier import (
+    Caf,
+    CafFakerService,
+    CafLoaderService,
+    CafValidatorService,
+    IdentifierComponent,
+)
+from .billing.integration import (
+    IntegrationComponent,
+    SendResult,
+    SiiDteService,
+    SiiStatus,
+)
+from .billing.trading_parties import (
+    Certificate,
+    MandatarioManagerService,
+    TradingPartiesComponent,
+)
+from .client import ApiClient
+from .exceptions import (
+    LibreDteApiError,
+    LibreDteConnectionError,
+    LibreDteRateLimitError,
+    LibreDteSdkError,
+)
+from .sdk import LibreDTE
+
+__all__ = [
+    'ApiClient',
+    'AutorizacionDte',
+    'BillingPackage',
+    'Caf',
+    'CafFakerService',
+    'CafLoaderService',
+    'CafValidatorService',
+    'Certificate',
+    'Document',
+    'DocumentBuilderService',
+    'DocumentComponent',
+    'DocumentDispatcherService',
+    'DocumentRendererService',
+    'Emisor',
+    'Envelope',
+    'IdentifierComponent',
+    'IntegrationComponent',
+    'LibreDTE',
+    'LibreDteApiError',
+    'LibreDteConnectionError',
+    'LibreDteRateLimitError',
+    'LibreDteSdkError',
+    'MandatarioManagerService',
+    'RenderResult',
+    'Rendering',
+    'SendResult',
+    'SiiDteService',
+    'SiiEnvironment',
+    'SiiStatus',
+    'TradingPartiesComponent',
+]

libredte_lib_sdk/billing/__init__.py

@@ -0,0 +1,31 @@
+"""
+Paquete `billing`: facturación electrónica de Chile.
+
+Organizado igual que la propia API (`paquete.componente.worker::operacion`):
+un subpaquete por componente (`document`, `identifier`, `trading_parties`,
+`integration`), cada uno con un `*Component` que agrupa sus servicios por
+worker. Agregar un worker nuevo (de un componente ya soportado, u otro
+componente/paquete de la API) es agregar un archivo y registrarlo en el
+`__init__.py` de su componente — no toca nada de lo demás.
+"""
+
+from __future__ import annotations
+
+from ..client import ApiClient
+from .document import DocumentComponent
+from .identifier import IdentifierComponent
+from .integration import IntegrationComponent
+from .trading_parties import TradingPartiesComponent
+
+__all__ = ['BillingPackage']
+
+
+class BillingPackage:
+    """Agrupa los componentes del paquete `billing` de la API."""
+
+    def __init__(self, client: ApiClient) -> None:
+        """Crea los componentes del paquete sobre el `ApiClient` dado."""
+        self.document = DocumentComponent(client)
+        self.identifier = IdentifierComponent(client)
+        self.trading_parties = TradingPartiesComponent(client)
+        self.integration = IntegrationComponent(client)

libredte_lib_sdk/billing/common.py

@@ -0,0 +1,29 @@
+"""Utilidades compartidas entre los componentes de `billing`."""
+
+from __future__ import annotations
+
+import base64
+
+
+class XmlPayloadMixin:
+    """
+    Mixin para un DTO cuyo dato principal es un XML en base64.
+
+    Espera un atributo `xml_base64: str` en la clase concreta (`Document`,
+    `Envelope`, `Caf`, ...) y expone `xml_bytes`/`xml` sobre él, para no
+    repetir esta misma conversión en cada DTO.
+    """
+
+    __slots__ = ()
+
+    xml_base64: str
+
+    @property
+    def xml_bytes(self) -> bytes:
+        """XML decodificado desde base64."""
+        return base64.b64decode(self.xml_base64)
+
+    @property
+    def xml(self) -> str:
+        """XML como texto (ISO-8859-1, la codificación que usa el SII)."""
+        return self.xml_bytes.decode('iso-8859-1')

libredte_lib_sdk/billing/document/__init__.py

@@ -0,0 +1,39 @@
+"""Componente `billing.document`: DTE — construcción, sobre y render."""
+
+from __future__ import annotations
+
+from ...client import ApiClient
+from .builder import DocumentBuilderService
+from .dispatcher import DocumentDispatcherService
+from .models import (
+    AutorizacionDte,
+    Document,
+    Emisor,
+    Envelope,
+    Rendering,
+    RenderResult,
+)
+from .renderer import DocumentRendererService
+
+__all__ = [
+    'AutorizacionDte',
+    'Document',
+    'DocumentBuilderService',
+    'DocumentComponent',
+    'DocumentDispatcherService',
+    'DocumentRendererService',
+    'Emisor',
+    'Envelope',
+    'RenderResult',
+    'Rendering',
+]
+
+
+class DocumentComponent:
+    """Agrupa los servicios de `billing.document`."""
+
+    def __init__(self, client: ApiClient) -> None:
+        """Crea los servicios del componente sobre el `ApiClient` dado."""
+        self.builder = DocumentBuilderService(client)
+        self.dispatcher = DocumentDispatcherService(client)
+        self.renderer = DocumentRendererService(client)

libredte_lib_sdk/billing/document/builder.py

@@ -0,0 +1,68 @@
+"""Servicio para `billing.document.builder`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...client import ApiClient
+from ..trading_parties.models import Certificate
+from .models import Document
+
+
+class DocumentBuilderService:
+    """
+    Construye documentos tributarios (`billing.document.builder`).
+
+    El mismo worker de la API sirve tanto para un borrador como para el
+    documento timbrado y firmado, según qué datos se le pasen — acá se
+    separa en dos métodos explícitos para que la intención de cada
+    llamada quede clara en el código que la usa.
+    """
+
+    _OPERATION = 'billing.document.builder::build'
+
+    def __init__(self, client: ApiClient) -> None:
+        """Guarda el `ApiClient` compartido usado para llamar a la API."""
+        self._client = client
+
+    def build_draft(self, parsed_data: dict[str, Any]) -> Document:
+        """
+        Emite el borrador de un DTE a partir de datos ya normalizados.
+
+        `parsed_data` es el `Encabezado`/`Detalle` (y demás nodos) del
+        formato DTE del SII, incluyendo `Encabezado.IdDoc.Folio` (el SDK
+        no asigna folios: eso lo decide quien llama, típicamente porque
+        lleva el correlativo). Sin CAF ni certificado, el resultado no
+        queda timbrado (`Document.is_timbrado` es `False`).
+        """
+        data = self._client.call(
+            self._OPERATION,
+            bag={'parsedData': parsed_data},
+        )
+        return Document.from_api(data)
+
+    def build_signed(
+        self,
+        parsed_data: dict[str, Any],
+        *,
+        caf_xml: str,
+        certificate: Certificate,
+    ) -> Document:
+        """
+        Genera el DTE real, timbrado y firmado.
+
+        Requiere un CAF real (XML tal como lo entrega el SII, cubriendo
+        el folio indicado en `parsed_data`) y el certificado digital del
+        emisor. Para pruebas, ambos se pueden generar con
+        `IdentifierComponent.caf_faker` y
+        `TradingPartiesComponent.mandatario_manager`.
+        """
+        data = self._client.call(
+            self._OPERATION,
+            bag={
+                'parsedData': parsed_data,
+                'caf': caf_xml,
+                'certificate': certificate.to_payload(),
+            },
+        )
+        return Document.from_api(data)

libredte_lib_sdk/billing/document/dispatcher.py

@@ -0,0 +1,49 @@
+"""Servicio para `billing.document.dispatcher`."""
+
+from __future__ import annotations
+
+from ...client import ApiClient
+from ..trading_parties.models import Certificate
+from .models import Emisor, Envelope
+
+
+class DocumentDispatcherService:
+    """
+    Arma el sobre `EnvioDTE` (`billing.document.dispatcher`).
+
+    Solo cubre `create`: envolver y firmar un documento ya construido.
+    El worker también expone `loadXml`/`validate`/`validateSchema`/
+    `validateSignature`, no incluidas acá.
+    """
+
+    _CREATE_OPERATION = 'billing.document.dispatcher::create'
+
+    def __init__(self, client: ApiClient) -> None:
+        """Guarda el `ApiClient` compartido usado para llamar a la API."""
+        self._client = client
+
+    def create(
+        self,
+        document_xml_base64: str,
+        *,
+        certificate: Certificate,
+        emisor: Emisor,
+    ) -> Envelope:
+        """
+        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`).
+        """
+        data = self._client.call(
+            self._CREATE_OPERATION,
+            bag={
+                'xmlDocument': document_xml_base64,
+                'certificate': certificate.to_payload(),
+                'emisor': emisor.to_payload(),
+            },
+        )
+        return Envelope.from_api(data)

libredte_lib_sdk/billing/document/models.py

@@ -0,0 +1,169 @@
+"""
+DTO del componente `billing.document`.
+
+No reimplementan el esquema DTE del SII (`Encabezado`/`Detalle`/etc. se
+pasan como `dict` tal cual ese formato, ver `builder.py`): solo tipan lo
+que el propio SDK arma o recibe de la API.
+"""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from typing import Any
+
+from ..common import XmlPayloadMixin
+
+
+@dataclass(frozen=True, slots=True)
+class AutorizacionDte:
+    """Resolución del SII que autoriza al emisor a emitir DTE."""
+
+    fecha_resolucion: str
+    numero_resolucion: int
+
+    def to_payload(self) -> dict[str, Any]:
+        """Payload esperado por la API para la autorización."""
+        return {
+            'fecha_resolucion': self.fecha_resolucion,
+            'numero_resolucion': self.numero_resolucion,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class Emisor:
+    """Datos del emisor requeridos para armar el sobre `EnvioDTE`."""
+
+    rut: str
+    razon_social: str
+    autorizacion_dte: AutorizacionDte
+
+    def to_payload(self) -> dict[str, Any]:
+        """Payload esperado por la API para el emisor del sobre."""
+        return {
+            'rut': self.rut,
+            'razon_social': self.razon_social,
+            'autorizacion_dte': self.autorizacion_dte.to_payload(),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class Document(XmlPayloadMixin):
+    """
+    Documento tributario construido.
+
+    Puede ser un borrador, un documento timbrado, o timbrado y firmado —
+    lo distingue `is_timbrado` (`ted is not None`), no una subclase
+    distinta: es el mismo recurso en distintos estados, según qué datos
+    se le hayan pasado a `DocumentBuilderService`.
+    """
+
+    id: str
+    datos: dict[str, Any]
+    ted: dict[str, Any] | None
+    xml_base64: str
+
+    @property
+    def is_timbrado(self) -> bool:
+        """Si el documento ya tiene Timbre Electrónico (TED)."""
+        return self.ted is not None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Document:
+        """Construye un `Document` desde el `data` que devuelve la API."""
+        return cls(
+            id=data['id'],
+            datos=data.get('datos') or {},
+            ted=data.get('ted'),
+            xml_base64=data['xml'],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Envelope(XmlPayloadMixin):
+    """Sobre `EnvioDTE` construido y firmado, listo para enviar al SII."""
+
+    tag: str
+    xml_base64: str
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Envelope:
+        """Construye un `Envelope` desde el `data` que devuelve la API."""
+        return cls(tag=data['tag'], xml_base64=data['xml'])
+
+
+@dataclass(frozen=True, slots=True)
+class Rendering:
+    """
+    Un archivo generado por `DocumentRendererService.render()`.
+
+    `content_base64` es el archivo completo en base64 (un PDF, un HTML,
+    lo que sea — `mime_type` dice qué es). `label` es la presentación
+    pedida en `renderings` (ej. `'tributaria'`, `'cedible'`); `copies`/
+    `copy_number` identifican esta copia entre las pedidas de ese mismo
+    `label` (ej. `copies=2, copy_number=1` es la primera de 2 copias
+    tributarias). El nombre de los campos en la API (`content`/
+    `mimeType`/`filename`/`copyNumber`) es camelCase; acá quedan en
+    snake_case como el resto del SDK.
+    """
+
+    content_base64: str
+    mime_type: str
+    filename: str
+    label: str
+    copies: int
+    copy_number: int
+
+    @property
+    def content_bytes(self) -> bytes:
+        """Contenido del archivo, decodificado desde base64."""
+        return base64.b64decode(self.content_base64)
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Rendering:
+        """Construye un `Rendering` desde un ítem de `data.renderings`."""
+        return cls(
+            content_base64=data['content'],
+            mime_type=data['mimeType'],
+            filename=data['filename'],
+            label=data['label'],
+            copies=data['copies'],
+            copy_number=data['copyNumber'],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RenderResult:
+    """
+    Resultado de `DocumentRendererService.render()`.
+
+    `renderings` trae un ítem por copia generada: por defecto (sin pedir
+    `renderings` explícito) es un único `'tributaria'`; pidiendo más de
+    una presentación y/o copia (ej. `renderings={'tributaria': 2,
+    'cedible': 1}`), trae uno por cada copia efectivamente generada —
+    una presentación que la API no pudo generar para ese documento (ej.
+    `'cedible'` en un tipo de documento sin acuse de recibo) se omite en
+    silencio, no rompe la llamada. `.first` es un atajo para el caso más
+    común (un solo archivo); `.by_label()` filtra por presentación
+    cuando se pidió más de una.
+    """
+
+    renderings: tuple[Rendering, ...]
+
+    @property
+    def first(self) -> Rendering:
+        """El primer archivo generado."""
+        return self.renderings[0]
+
+    def by_label(self, label: str) -> tuple[Rendering, ...]:
+        """Los renderings de una presentación (ej. `'tributaria'`)."""
+        return tuple(r for r in self.renderings if r.label == label)
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> RenderResult:
+        """Construye un `RenderResult` desde el `data` que devuelve la API."""
+        return cls(
+            renderings=tuple(
+                Rendering.from_api(item) for item in data['renderings']
+            ),
+        )

libredte_lib_sdk/billing/document/renderer.py

@@ -0,0 +1,60 @@
+"""Servicio para `billing.document.renderer`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...client import ApiClient
+from .models import RenderResult
+
+
+class DocumentRendererService:
+    """
+    Renderiza un documento tributario (`billing.document.renderer`).
+
+    Soporta `format='html'` y `format='pdf'`. La API devuelve siempre
+    `data.renderings`, una lista de archivos en base64 — ver
+    `RenderResult`/`Rendering` en `models.py`.
+    """
+
+    _OPERATION = 'billing.document.renderer::render'
+
+    def __init__(self, client: ApiClient) -> None:
+        """Guarda el `ApiClient` compartido usado para llamar a la API."""
+        self._client = client
+
+    def render(
+        self,
+        document_xml_base64: str,
+        *,
+        format: str = 'pdf',  # noqa: A002
+        renderings: dict[str, int] | None = None,
+    ) -> RenderResult:
+        """
+        Genera el PDF (u otro formato soportado por la API) de un documento.
+
+        Sirve tanto para un borrador como para un documento ya timbrado y
+        firmado: el resultado depende solo del XML que se le pase (ej.
+        `Document.xml_base64`).
+
+        Sin `renderings`, la API genera una única copia `'tributaria'`
+        (comportamiento por defecto). `renderings` pide presentaciones y
+        cantidad de copias de cada una — ej. `{'tributaria': 1,
+        'cedible': 1}` — y la API rechaza (`LibreDteApiError`, 500) una
+        presentación que no existe, o si ninguna de las pedidas pudo
+        generarse (ej. pedir solo `'cedible'` para un tipo de documento
+        sin acuse de recibo). Ver `RenderResult` para cómo se identifica
+        cada copia en la respuesta.
+        """
+        renderer_options: dict[str, Any] = {'format': format}
+        if renderings is not None:
+            renderer_options['renderings'] = renderings
+
+        data = self._client.call(
+            self._OPERATION,
+            bag={
+                'xmlDocument': document_xml_base64,
+                'options': {'renderer': renderer_options},
+            },
+        )
+        return RenderResult.from_api(data)

libredte_lib_sdk/billing/enums.py

@@ -0,0 +1,18 @@
+"""Enumeraciones del paquete `billing`."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class SiiEnvironment(IntEnum):
+    """
+    Ambiente del SII contra el que se opera.
+
+    Convención estándar del ecosistema LibreDTE. El default es
+    `CERTIFICATION` a propósito: nadie debería terminar enviando algo a
+    producción por haber omitido este argumento.
+    """
+
+    CERTIFICATION = 0
+    PRODUCTION = 1

libredte_lib_sdk/billing/identifier/__init__.py

@@ -0,0 +1,27 @@
+"""Componente `billing.identifier`: folios de documentos tributarios."""
+
+from __future__ import annotations
+
+from ...client import ApiClient
+from .caf_faker import CafFakerService
+from .caf_loader import CafLoaderService
+from .caf_validator import CafValidatorService
+from .models import Caf
+
+__all__ = [
+    'Caf',
+    'CafFakerService',
+    'CafLoaderService',
+    'CafValidatorService',
+    'IdentifierComponent',
+]
+
+
+class IdentifierComponent:
+    """Agrupa los servicios de `billing.identifier`."""
+
+    def __init__(self, client: ApiClient) -> None:
+        """Crea los servicios del componente sobre el `ApiClient` dado."""
+        self.caf_faker = CafFakerService(client)
+        self.caf_loader = CafLoaderService(client)
+        self.caf_validator = CafValidatorService(client)

libredte_lib_sdk/billing/identifier/caf_faker.py

@@ -0,0 +1,49 @@
+"""Servicio para `billing.identifier.caf_faker`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...client import ApiClient
+from .models import Caf
+
+
+class CafFakerService:
+    """
+    Genera CAF ficticios (`billing.identifier.caf_faker::create`).
+
+    Solo para pruebas/desarrollo: el CAF resultante no está autorizado
+    de verdad por el SII, pero permite ejercitar el timbrado/firma de un
+    documento (y, con eso, el resto del flujo) sin depender de un folio
+    real. El SDK lo usa así para poder probarse de punta a punta.
+    """
+
+    _OPERATION = 'billing.identifier.caf_faker::create'
+
+    def __init__(self, client: ApiClient) -> None:
+        """Guarda el `ApiClient` compartido usado para llamar a la API."""
+        self._client = client
+
+    def create(
+        self,
+        emisor: dict[str, Any],
+        *,
+        codigo_documento: int,
+        folio_desde: int = 1,
+        folio_hasta: int | None = None,
+    ) -> Caf:
+        """
+        Genera un CAF ficticio para `emisor` y `codigo_documento`.
+
+        `emisor` es un `dict` con `rut`/`razon_social`, tal como lo
+        espera la API. `folio_hasta` por defecto cubre solo
+        `folio_desde` (un único folio), igual que hace la API.
+        """
+        data = self._client.call(
+            self._OPERATION,
+            emisor=emisor,
+            codigoDocumento=codigo_documento,
+            folioDesde=folio_desde,
+            folioHasta=folio_hasta,
+        )
+        return Caf.from_api(data)

libredte_lib_sdk/billing/identifier/caf_loader.py

@@ -0,0 +1,31 @@
+"""Servicio para `billing.identifier.caf_loader`."""
+
+from __future__ import annotations
+
+from ...client import ApiClient
+from .models import Caf
+
+
+class CafLoaderService:
+    """
+    Carga un CAF real (`billing.identifier.caf_loader::load`).
+
+    A diferencia de `CafFakerService` (que genera un CAF ficticio para
+    pruebas), esto carga el XML de un CAF **real** — el que el SII le
+    entrega al emisor y que la app que use este SDK deja subir al
+    usuario — y lo entrega como la misma entidad `Caf` que devuelve
+    `CafFakerService.create`, con su folio/vigencia ya resueltos. Sin
+    esto, `DocumentBuilderService.build_signed()` no tiene de dónde
+    sacar un CAF real para timbrar en producción.
+    """
+
+    _OPERATION = 'billing.identifier.caf_loader::load'
+
+    def __init__(self, client: ApiClient) -> None:
+        """Guarda el `ApiClient` compartido usado para llamar a la API."""
+        self._client = client
+
+    def load(self, xml_base64: str) -> Caf:
+        """Carga el CAF cuyo XML (en base64) es `xml_base64`."""
+        data = self._client.call(self._OPERATION, xml=xml_base64)
+        return Caf.from_api(data)

libredte_lib_sdk/billing/identifier/caf_validator.py

@@ -0,0 +1,36 @@
+"""Servicio para `billing.identifier.caf_validator`."""
+
+from __future__ import annotations
+
+from ...client import ApiClient
+from .models import Caf
+
+
+class CafValidatorService:
+    """
+    Valida un CAF (`billing.identifier.caf_validator::validate`).
+
+    Valida la firma y las llaves públicas/privadas asociadas al CAF —
+    útil antes de usarlo en `DocumentBuilderService.build_signed()`,
+    para poder avisarle al usuario que su CAF no es válido (ej. vencido)
+    con un error claro, en vez de que la falla aparezca recién al
+    intentar timbrar un documento.
+    """
+
+    _OPERATION = 'billing.identifier.caf_validator::validate'
+
+    def __init__(self, client: ApiClient) -> None:
+        """Guarda el `ApiClient` compartido usado para llamar a la API."""
+        self._client = client
+
+    def validate(self, caf_xml_base64: str) -> Caf:
+        """
+        Valida el CAF cuyo XML (en base64) es `caf_xml_base64`.
+
+        La API espera el mismo XML en base64 que `CafLoaderService.load`
+        (el parámetro de la operación se llama `caf`, no `xml`, pero es
+        el mismo dato). Devuelve el `Caf` ya validado si es válido;
+        levanta `LibreDteApiError` si no lo es.
+        """
+        data = self._client.call(self._OPERATION, caf=caf_xml_base64)
+        return Caf.from_api(data)