libredte_lib_sdk.billing.document package

Submodules

Module contents

Componente billing.document: DTE — construcción, sobre y render.

class libredte_lib_sdk.billing.document.Document(id: str, datos: dict[str, Any], ted: dict[str, Any] | None, xml_base64: str)

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

datos: dict[str, Any]

classmethod from_api(data: dict[str, Any]) → Document: Construye un Document desde el data que devuelve la API.

id: str

property is_timbrado: bool: Si el documento ya tiene Timbre Electrónico (TED).

ted: dict[str, Any] | None

xml_base64: str

class libredte_lib_sdk.billing.document.DocumentBag(datos: dict[str, Any], document_type: dict[str, Any], stamp_xml: str | None, extra: dict[str, Any] | None, auth: dict[str, Any] | None, raw: dict[str, Any])

Bases: object

Bolsa normalizada devuelta por document.loader::loadXml.

No trae el XML del documento ni id — solo la bolsa ya normalizada: datos (Encabezado/Detalle), document_type (metadatos del tipo de documento: codigo, nombre, categoria, es_boleta, etc., sin tipar) y stamp_xml (el TED, como XML plano, no en base64 ni parseado). Sirve para reconstruir los datos de un DTE ya emitido a partir de su XML.

auth: dict[str, Any] | None

datos: dict[str, Any]

document_type: dict[str, Any]

extra: dict[str, Any] | None

classmethod from_api(data: dict[str, Any]) → DocumentBag: Construye un DocumentBag desde el data de la API.

raw: dict[str, Any]

stamp_xml: str | None

class libredte_lib_sdk.billing.document.DocumentBuilderService(client: ApiClient)

Bases: object

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.

build_draft(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).

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

class libredte_lib_sdk.billing.document.DocumentComponent(client: ApiClient)

Bases: object

Agrupa los servicios de billing.document.

class libredte_lib_sdk.billing.document.DocumentDispatcherService(client: ApiClient)

Bases: object

Arma y valida el sobre EnvioDTE (billing.document.dispatcher).

create(document_xml_base64: str, *, certificate: Certificate, emisor: dict[str, Any]) → 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.

load_xml(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).

validate(source: str) → dict[str, Any]

Valida un sobre EnvioDTE ya construido (source, XML en base64).

Devuelve el XML del sobre, como dict (representación parseada, ej. EnvioDTE.SetDTE.Caratula…).

validate_schema(source: str) → dict[str, Any]: Valida source contra el esquema XSD del sobre EnvioDTE.

validate_signature(source: str) → list[dict[str, Any]]

Valida cada firma electrónica encontrada en el sobre.

Un sobre trae más de una firma (la del DTE y la del propio EnvioDTE) — devuelve una lista, un ítem por firma. Cada ítem es un dict vacío en caso de éxito.

class libredte_lib_sdk.billing.document.DocumentEnvelope(tag: str, xml_base64: str)

Bases: XmlPayloadMixin

Sobre EnvioDTE construido y firmado, listo para enviar al SII.

classmethod from_api(data: dict[str, Any]) → DocumentEnvelope: Construye un DocumentEnvelope desde el data de la API.

tag: str

xml_base64: str

class libredte_lib_sdk.billing.document.DocumentExamplesService(client: ApiClient)

Bases: object

Ejemplos de documentos reales (billing.document.examples).

Son los mismos casos de prueba, validados, que usa la suite de tests 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.parsed_data 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.

get(example_id: str) → Example: Entrega los datos completos del ejemplo example_id.

list() → list[ExampleSummary]: Lista los ejemplos disponibles (id, category, case).

class libredte_lib_sdk.billing.document.DocumentLoaderService(client: ApiClient)

Bases: object

Carga un documento tributario completo desde su XML.

Solo cubre loadXml — pensado para reconstruir los datos normalizados de un DTE ya emitido (timbrado y firmado) a partir de su XML, ej. un documento recibido de un tercero o recuperado de un respaldo.

load_xml(xml_base64: str) → DocumentBag: Carga y normaliza el documento cuyo XML (base64) es xml_base64.

class libredte_lib_sdk.billing.document.DocumentRendererService(client: ApiClient)

Bases: object

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/RenderedDocument en models.py.

render(document_xml_base64: str, *, format: str = 'pdf', 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.

class libredte_lib_sdk.billing.document.DocumentValidatorService(client: ApiClient)

Bases: object

Valida un documento tributario ya construido (billing.document).

source es el XML del documento en base64 (ej. Document.xml_base64 de un documento ya construido) — la API acepta también la bolsa o el documento ya cargado, pero el SDK solo necesita pasar el XML.

validate(source: str) → None

Valida los datos del documento (source, XML en base64).

No devuelve valor: si el documento no es válido, la API levanta LibreDteApiError (no hay un resultado «inválido» con detalle).

validate_schema(source: str) → dict[str, Any]

Valida source contra el esquema XSD del documento.

Devuelve el XML ya validado, como dict (la representación parseada del XML, ej. DTE.Documento.Encabezado…) — el SDK no la tipa, ya que su forma depende del tipo de documento.

validate_signature(source: str) → dict[str, Any]

Valida la firma electrónica del documento.

Devuelve un dict vacío en caso de éxito. Si la firma no es válida, la API levanta LibreDteApiError.

class libredte_lib_sdk.billing.document.Example(id: str, parsed_data: dict[str, Any], expected: dict[str, Any])

Bases: object

Un ejemplo de documento, tal como lo devuelve examples::get().

parsed_data es directamente el parsedData que esperan DocumentBuilderService.build_draft()/.build_signed() — mismo Encabezado/Detalle que usa el resto del SDK, sin transformación. expected son los valores esperados del caso (totales, etc.) que usa la suite de tests de libredte-lib-core para validarlo — información de referencia, no un dato del documento en sí.

expected: dict[str, Any]

classmethod from_api(data: dict[str, Any]) → Example: Construye un Example desde el data que devuelve la API.

id: str

parsed_data: dict[str, Any]

class libredte_lib_sdk.billing.document.ExampleSummary(id: str, category: str, case: str)

Bases: object

Un ejemplo listado por DocumentExamplesService.list().

case: str

category: str

classmethod from_api(data: dict[str, Any]) → ExampleSummary: Construye un ExampleSummary desde un ítem de la lista.

id: str

class libredte_lib_sdk.billing.document.RenderResult(renderings: tuple[RenderedDocument, ...])

Bases: object

Resultado de un renderizador.

Ej. DocumentRendererService.render(), PayrollRendererService .render(). renderings trae un ítem por copia generada. Para document.renderer: 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. Para payroll.renderer (que no modela presentaciones) siempre trae un único elemento, sin label. .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.

by_label(label: str) → tuple[RenderedDocument, ...]: Los renderings de una presentación (ej. “tributaria”).

property first: RenderedDocument: El primer archivo generado.

classmethod from_api(data: dict[str, Any]) → RenderResult: Construye un RenderResult desde el data que devuelve la API.

renderings: tuple[RenderedDocument, ...]

class libredte_lib_sdk.billing.document.RenderedDocument(content_base64: str, mime_type: str, filename: str, label: str | None, copies: int, copy_number: int)

Bases: object

Un archivo generado por un renderizador.

Ej. DocumentRendererService.render(), PayrollRendererService .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”) cuando el renderizador modela más de una presentación posible; None cuando no aplica (ej. una liquidación de sueldo, que siempre es un único archivo). 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

property content_bytes: bytes: Contenido del archivo, decodificado desde base64.

copies: int

copy_number: int

filename: str

classmethod from_api(data: dict[str, Any]) → RenderedDocument: Construye desde un ítem de data.renderings.

label: str | None

mime_type: str