sunat-ubl 0.2.0__tar.gz

sunat_ubl-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+salida/
+.coverage
+htmlcov/
+.DS_Store

sunat_ubl-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabricio Miranda Vila
+
+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.

sunat_ubl-0.2.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: sunat-ubl
+Version: 0.2.0
+Summary: Genera y firma XML UBL 2.1 de facturas y boletas electrónicas para SUNAT (Perú), y lee CDR. Núcleo sin dependencias.
+Author: Fabricio Miranda Vila
+License: MIT
+License-File: LICENSE
+Keywords: boleta electronica,cdr,cpe,factura electronica,firma digital,peru,sunat,ubl,xmldsig
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: lxml>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: signxml>=4; extra == 'dev'
+Provides-Extra: firma
+Requires-Dist: lxml>=5; extra == 'firma'
+Requires-Dist: signxml>=4; extra == 'firma'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="assets/social-preview.png" alt="sunat-ubl: facturas y boletas electrónicas de SUNAT en Python, sin dependencias" width="860">
+</div>
+
+# sunat-ubl
+
+[![CI](https://github.com/Giovanniedu/sunat-ubl/actions/workflows/ci.yml/badge.svg)](https://github.com/Giovanniedu/sunat-ubl/actions)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://pypi.org/project/sunat-ubl/)
+[![Licencia](https://img.shields.io/badge/licencia-MIT-green.svg)](LICENSE)
+[![Dependencias](https://img.shields.io/badge/dependencias-0-green.svg)](pyproject.toml)
+
+Genera el **XML UBL 2.1** de facturas y boletas electrónicas del Perú, lo **firma digitalmente**
+y lee el **CDR** de SUNAT. El núcleo no tiene dependencias: solo la librería estándar de Python.
+
+<img src="assets/flujo.png" alt="Del dato al comprobante aceptado: JSON → sunat_ubl → XML UBL 2.1 firmado → SUNAT SEE-SOL → CDR" width="860">
+
+## Por qué existe
+
+Integrar con el SEE-SOL de SUNAT obliga a armar a mano un XML UBL 2.1 con namespaces, catálogos
+de afectación del IGV y reglas de redondeo que, si se equivocan por un céntimo, terminan en un
+rechazo con un código y sin explicación útil. Esta librería resuelve esa capa:
+
+- **Cuadratura exacta.** Si partes de un precio con IGV (100.00), la base queda en 84.75 y el IGV
+  en 15.25, no en 15.26. Base + IGV siempre suma lo que paga el cliente.
+- **Firma digital XMLDSig** (RSA-SHA256, SHA-256, exc-c14n) insertada en `ext:UBLExtensions`,
+  que es donde la exige SUNAT.
+- **Catálogos oficiales**: afectación del IGV (10, 20, 30, 40), tributos (1000, 9995, 9997, 9998),
+  tipos de documento de identidad y unidades de medida.
+- **Nombre de archivo correcto**: `RUC-TIPO-SERIE-NUMERO.xml`.
+- **Validación temprana** de RUC (módulo 11), DNI, series y montos, con mensajes en español.
+- **CDR**: lee el ZIP o el XML que devuelve SUNAT y expone código, descripción y observaciones.
+
+## Instalación
+
+```bash
+pip install sunat-ubl                 # núcleo, sin dependencias
+pip install "sunat-ubl[firma]"        # + firma digital (signxml, lxml)
+```
+
+## Uso rápido
+
+```python
+from datetime import date
+from sunat_ubl import Cliente, Comprobante, Emisor, Linea, guardar
+
+factura = Comprobante(
+    tipo="01", serie="F001", numero=1, fecha=date(2026, 10, 30),
+    emisor=Emisor(ruc="20999999990", razon_social="SERVICIOS DEMO PERU SAC"),
+    cliente=Cliente(tipo_doc="6", numero="20512345671", razon_social="CLIENTE SAC"),
+    lineas=[
+        Linea("Consultoría", cantidad=2, valor_unitario="100.00", unidad="ZZ"),
+        Linea.desde_precio_con_igv("Soporte", cantidad=1, precio_con_igv=118),
+        Linea("Servicio exonerado", cantidad=1, valor_unitario="50.00", tipo_afectacion="20"),
+    ],
+)
+guardar(factura, "salida")  # salida/20999999990-01-F001-1.xml
+```
+
+## Firma digital
+
+El XML sale sin firmar por defecto. Para firmarlo necesitas el certificado digital de tu empresa
+(PEM) y su clave privada:
+
+```python
+from sunat_ubl import firmar, firmar_xml, verificar_firma
+
+xml_firmado = firmar(factura, "certificado.pem", "clave.pem")
+# o firma un XML ya generado:
+xml_firmado = firmar_xml(open("20999999990-01-F001-1.xml", "rb").read(), "certificado.pem", "clave.pem")
+
+verificar_firma(xml_firmado, "certificado.pem")  # True si nadie lo alteró
+```
+
+- La firma se inserta en `ext:UBLExtensions/ext:ExtensionContent` (posición que exige SUNAT).
+- Algoritmos: `rsa-sha256`, digest `sha256`, canonicalización exclusiva C14N.
+- El documento firmado no se reindenta: cualquier cambio de espacios invalidaría la firma.
+
+## CLI
+
+```bash
+sunat-ubl generar examples/factura.json -o salida
+sunat-ubl generar examples/factura.json -o salida --cert cert.pem --clave key.pem
+sunat-ubl firmar factura.xml --cert cert.pem --clave key.pem [-o salida.xml]
+sunat-ubl cdr R-20999999990-01-F001-1.zip
+sunat-ubl ruc 20100070970
+```
+
+```
+$ sunat-ubl cdr R-20999999990-01-F001-1.zip
+ACEPTADO CON OBSERVACIONES (0): El comprobante fue registrado exitosamente
+comprobante: F001-1
+observación: 2335 - El comprobante fue aceptado
+```
+
+## Formato JSON
+
+`examples/factura.json` es un ejemplo completo. Las líneas aceptan `valor_unitario` (sin IGV) o
+`precio_con_igv` (lo que paga el cliente):
+
+```json
+{
+  "tipo": "01", "serie": "F001", "numero": 1,
+  "fecha": "2026-10-30", "hora": "15:42:10", "moneda": "PEN",
+  "emisor":  { "ruc": "20999999990", "razon_social": "SERVICIOS DEMO PERU SAC" },
+  "cliente": { "tipo_doc": "6", "numero": "20512345671", "razon_social": "CLIENTE SAC" },
+  "lineas": [
+    { "descripcion": "Consultoría", "cantidad": 2, "valor_unitario": 100.0, "unidad": "ZZ" },
+    { "descripcion": "Soporte", "cantidad": 1, "precio_con_igv": 118.0, "unidad": "ZZ" }
+  ]
+}
+```
+
+## Qué hace y qué no
+
+| Sí | Todavía no |
+| --- | --- |
+| XML UBL 2.1 de factura (01) y boleta (03) | Notas de crédito (07) y débito (08) |
+| IGV, exonerado, inafecto y exportación | ISC e ICBPER |
+| Firma digital XMLDSig | Envío al SEE-SOL (SUNAT solo acepta SOAP con certificado) |
+| Lectura de CDR | Validación contra el XSD oficial de SUNAT |
+| Totales, catálogos y validaciones | |
+
+> **Honestidad primero:** la estructura del XML sigue el estándar UBL 2.1 y la firma verifica
+> criptográficamente, pero este proyecto todavía **no ha sido validado contra el XSD oficial de
+> SUNAT ni probado en el SEE beta**. Si vas a emitir comprobantes reales, pruébalo primero en el
+> entorno beta del contribuyente con tu certificado.
+
+## API
+
+```python
+from sunat_ubl import a_xml, construir, guardar, leer_cdr, validar_ruc
+
+xml_bytes = a_xml(factura)           # bytes UTF-8 sin firmar
+raiz = construir(factura)            # xml.etree.ElementTree.Element
+cdr = leer_cdr("R-...-CDR.zip")
+cdr.aceptado, cdr.codigo, cdr.notas, cdr.referencia
+```
+
+## English summary
+
+`sunat-ubl` generates the UBL 2.1 XML required by SUNAT (Peru's tax authority) for electronic
+invoices and sales receipts, signs it with XMLDSig, and reads the CDR response. The core has
+**zero dependencies**; signing is an optional extra. It handles IGV rounding edge cases (the
+"1 céntimo" mismatch), validates RUC/DNI/series, and produces the exact filename SUNAT expects.
+
+## Desarrollo
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest                                                # 62 tests
+```
+
+## Licencia
+
+MIT. Ver [LICENSE](LICENSE).

sunat_ubl-0.2.0/README.md

@@ -0,0 +1,156 @@
+<div align="center">
+  <img src="assets/social-preview.png" alt="sunat-ubl: facturas y boletas electrónicas de SUNAT en Python, sin dependencias" width="860">
+</div>
+
+# sunat-ubl
+
+[![CI](https://github.com/Giovanniedu/sunat-ubl/actions/workflows/ci.yml/badge.svg)](https://github.com/Giovanniedu/sunat-ubl/actions)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://pypi.org/project/sunat-ubl/)
+[![Licencia](https://img.shields.io/badge/licencia-MIT-green.svg)](LICENSE)
+[![Dependencias](https://img.shields.io/badge/dependencias-0-green.svg)](pyproject.toml)
+
+Genera el **XML UBL 2.1** de facturas y boletas electrónicas del Perú, lo **firma digitalmente**
+y lee el **CDR** de SUNAT. El núcleo no tiene dependencias: solo la librería estándar de Python.
+
+<img src="assets/flujo.png" alt="Del dato al comprobante aceptado: JSON → sunat_ubl → XML UBL 2.1 firmado → SUNAT SEE-SOL → CDR" width="860">
+
+## Por qué existe
+
+Integrar con el SEE-SOL de SUNAT obliga a armar a mano un XML UBL 2.1 con namespaces, catálogos
+de afectación del IGV y reglas de redondeo que, si se equivocan por un céntimo, terminan en un
+rechazo con un código y sin explicación útil. Esta librería resuelve esa capa:
+
+- **Cuadratura exacta.** Si partes de un precio con IGV (100.00), la base queda en 84.75 y el IGV
+  en 15.25, no en 15.26. Base + IGV siempre suma lo que paga el cliente.
+- **Firma digital XMLDSig** (RSA-SHA256, SHA-256, exc-c14n) insertada en `ext:UBLExtensions`,
+  que es donde la exige SUNAT.
+- **Catálogos oficiales**: afectación del IGV (10, 20, 30, 40), tributos (1000, 9995, 9997, 9998),
+  tipos de documento de identidad y unidades de medida.
+- **Nombre de archivo correcto**: `RUC-TIPO-SERIE-NUMERO.xml`.
+- **Validación temprana** de RUC (módulo 11), DNI, series y montos, con mensajes en español.
+- **CDR**: lee el ZIP o el XML que devuelve SUNAT y expone código, descripción y observaciones.
+
+## Instalación
+
+```bash
+pip install sunat-ubl                 # núcleo, sin dependencias
+pip install "sunat-ubl[firma]"        # + firma digital (signxml, lxml)
+```
+
+## Uso rápido
+
+```python
+from datetime import date
+from sunat_ubl import Cliente, Comprobante, Emisor, Linea, guardar
+
+factura = Comprobante(
+    tipo="01", serie="F001", numero=1, fecha=date(2026, 10, 30),
+    emisor=Emisor(ruc="20999999990", razon_social="SERVICIOS DEMO PERU SAC"),
+    cliente=Cliente(tipo_doc="6", numero="20512345671", razon_social="CLIENTE SAC"),
+    lineas=[
+        Linea("Consultoría", cantidad=2, valor_unitario="100.00", unidad="ZZ"),
+        Linea.desde_precio_con_igv("Soporte", cantidad=1, precio_con_igv=118),
+        Linea("Servicio exonerado", cantidad=1, valor_unitario="50.00", tipo_afectacion="20"),
+    ],
+)
+guardar(factura, "salida")  # salida/20999999990-01-F001-1.xml
+```
+
+## Firma digital
+
+El XML sale sin firmar por defecto. Para firmarlo necesitas el certificado digital de tu empresa
+(PEM) y su clave privada:
+
+```python
+from sunat_ubl import firmar, firmar_xml, verificar_firma
+
+xml_firmado = firmar(factura, "certificado.pem", "clave.pem")
+# o firma un XML ya generado:
+xml_firmado = firmar_xml(open("20999999990-01-F001-1.xml", "rb").read(), "certificado.pem", "clave.pem")
+
+verificar_firma(xml_firmado, "certificado.pem")  # True si nadie lo alteró
+```
+
+- La firma se inserta en `ext:UBLExtensions/ext:ExtensionContent` (posición que exige SUNAT).
+- Algoritmos: `rsa-sha256`, digest `sha256`, canonicalización exclusiva C14N.
+- El documento firmado no se reindenta: cualquier cambio de espacios invalidaría la firma.
+
+## CLI
+
+```bash
+sunat-ubl generar examples/factura.json -o salida
+sunat-ubl generar examples/factura.json -o salida --cert cert.pem --clave key.pem
+sunat-ubl firmar factura.xml --cert cert.pem --clave key.pem [-o salida.xml]
+sunat-ubl cdr R-20999999990-01-F001-1.zip
+sunat-ubl ruc 20100070970
+```
+
+```
+$ sunat-ubl cdr R-20999999990-01-F001-1.zip
+ACEPTADO CON OBSERVACIONES (0): El comprobante fue registrado exitosamente
+comprobante: F001-1
+observación: 2335 - El comprobante fue aceptado
+```
+
+## Formato JSON
+
+`examples/factura.json` es un ejemplo completo. Las líneas aceptan `valor_unitario` (sin IGV) o
+`precio_con_igv` (lo que paga el cliente):
+
+```json
+{
+  "tipo": "01", "serie": "F001", "numero": 1,
+  "fecha": "2026-10-30", "hora": "15:42:10", "moneda": "PEN",
+  "emisor":  { "ruc": "20999999990", "razon_social": "SERVICIOS DEMO PERU SAC" },
+  "cliente": { "tipo_doc": "6", "numero": "20512345671", "razon_social": "CLIENTE SAC" },
+  "lineas": [
+    { "descripcion": "Consultoría", "cantidad": 2, "valor_unitario": 100.0, "unidad": "ZZ" },
+    { "descripcion": "Soporte", "cantidad": 1, "precio_con_igv": 118.0, "unidad": "ZZ" }
+  ]
+}
+```
+
+## Qué hace y qué no
+
+| Sí | Todavía no |
+| --- | --- |
+| XML UBL 2.1 de factura (01) y boleta (03) | Notas de crédito (07) y débito (08) |
+| IGV, exonerado, inafecto y exportación | ISC e ICBPER |
+| Firma digital XMLDSig | Envío al SEE-SOL (SUNAT solo acepta SOAP con certificado) |
+| Lectura de CDR | Validación contra el XSD oficial de SUNAT |
+| Totales, catálogos y validaciones | |
+
+> **Honestidad primero:** la estructura del XML sigue el estándar UBL 2.1 y la firma verifica
+> criptográficamente, pero este proyecto todavía **no ha sido validado contra el XSD oficial de
+> SUNAT ni probado en el SEE beta**. Si vas a emitir comprobantes reales, pruébalo primero en el
+> entorno beta del contribuyente con tu certificado.
+
+## API
+
+```python
+from sunat_ubl import a_xml, construir, guardar, leer_cdr, validar_ruc
+
+xml_bytes = a_xml(factura)           # bytes UTF-8 sin firmar
+raiz = construir(factura)            # xml.etree.ElementTree.Element
+cdr = leer_cdr("R-...-CDR.zip")
+cdr.aceptado, cdr.codigo, cdr.notas, cdr.referencia
+```
+
+## English summary
+
+`sunat-ubl` generates the UBL 2.1 XML required by SUNAT (Peru's tax authority) for electronic
+invoices and sales receipts, signs it with XMLDSig, and reads the CDR response. The core has
+**zero dependencies**; signing is an optional extra. It handles IGV rounding edge cases (the
+"1 céntimo" mismatch), validates RUC/DNI/series, and produces the exact filename SUNAT expects.
+
+## Desarrollo
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest                                                # 62 tests
+```
+
+## Licencia
+
+MIT. Ver [LICENSE](LICENSE).

sunat_ubl-0.2.0/examples/factura.json

@@ -0,0 +1,50 @@
+{
+  "tipo": "01",
+  "serie": "F001",
+  "numero": 1,
+  "fecha": "2026-10-30",
+  "hora": "15:42:10",
+  "moneda": "PEN",
+  "orden_compra": "OC-2026-0042",
+  "observacion": "Gracias por su compra",
+  "emisor": {
+    "ruc": "20999999990",
+    "razon_social": "SERVICIOS DEMO PERU SAC",
+    "nombre_comercial": "Demo Perú",
+    "direccion": "AV. SIEMPRE VIVA 123",
+    "ubigeo": "150101"
+  },
+  "cliente": {
+    "tipo_doc": "6",
+    "numero": "20512345671",
+    "razon_social": "CLIENTE DE PRUEBA SAC",
+    "direccion": "JR. LAMBAYEQUE 456",
+    "email": "compras@cliente.pe"
+  },
+  "lineas": [
+    {
+      "codigo": "SRV-001",
+      "descripcion": "SERVICIO DE CONSULTORIA EN CRECIMIENTO (10 HORAS)",
+      "cantidad": 2,
+      "valor_unitario": 100.0,
+      "tipo_afectacion": "10",
+      "unidad": "ZZ"
+    },
+    {
+      "codigo": "SRV-002",
+      "descripcion": "SOPORTE TECNICO MENSUAL",
+      "cantidad": 1,
+      "precio_con_igv": 118.0,
+      "tipo_afectacion": "10",
+      "unidad": "ZZ"
+    },
+    {
+      "codigo": "ADM-001",
+      "descripcion": "SERVICIO EXONERADO DEL IGV (ART. 2 LEY 27037)",
+      "cantidad": 1,
+      "valor_unitario": 50.0,
+      "tipo_afectacion": "20",
+      "unidad": "ZZ"
+    }
+  ]
+}

sunat_ubl-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sunat-ubl"
+version = "0.2.0"
+description = "Genera y firma XML UBL 2.1 de facturas y boletas electrónicas para SUNAT (Perú), y lee CDR. Núcleo sin dependencias."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Fabricio Miranda Vila" }]
+keywords = ["sunat", "factura electronica", "boleta electronica", "ubl", "peru", "cpe", "cdr", "firma digital", "xmldsig"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Office/Business :: Financial :: Accounting",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+firma = ["signxml>=4", "lxml>=5"]
+dev = ["pytest>=8", "signxml>=4", "lxml>=5", "cryptography>=42"]
+
+[project.scripts]
+sunat-ubl = "sunat_ubl.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sunat_ubl"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "-q"

sunat_ubl-0.2.0/src/sunat_ubl/__init__.py

@@ -0,0 +1,39 @@
+"""sunat-ubl: facturas y boletas electrónicas del Perú sin dependencias."""
+
+from __future__ import annotations
+
+from .catalogs import TASA_IGV, TIPOS_COMPROBANTE, TIPOS_DOC_IDENTIDAD, afectacion
+from .cdr import Cdr, leer_cdr
+from .firma import firmar, firmar_xml, verificar_firma
+from .generator import a_xml, construir, guardar
+from .json_input import comprobante_desde_archivo, comprobante_desde_dict
+from .models import Cliente, Comprobante, Emisor, Linea, dinero
+from .validation import validar_dni, validar_ruc, validar_serie
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "TASA_IGV",
+    "TIPOS_COMPROBANTE",
+    "TIPOS_DOC_IDENTIDAD",
+    "Cdr",
+    "Cliente",
+    "Comprobante",
+    "Emisor",
+    "Linea",
+    "a_xml",
+    "afectacion",
+    "comprobante_desde_archivo",
+    "comprobante_desde_dict",
+    "construir",
+    "firmar",
+    "firmar_xml",
+    "verificar_firma",
+    "dinero",
+    "guardar",
+    "leer_cdr",
+    "validar_dni",
+    "validar_ruc",
+    "validar_serie",
+    "__version__",
+]

sunat_ubl-0.2.0/src/sunat_ubl/catalogs.py

@@ -0,0 +1,87 @@
+"""Catálogos oficiales de SUNAT usados en comprobantes electrónicos."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+TASA_IGV = Decimal("0.18")
+
+TIPOS_COMPROBANTE = {
+    "01": "Factura electrónica",
+    "03": "Boleta de venta electrónica",
+}
+
+PREFIJO_SERIE = {
+    "01": "F",
+    "03": "B",
+}
+
+TIPOS_DOC_IDENTIDAD = {
+    "0": "Doc. tributario no domiciliado sin RUC",
+    "1": "DNI",
+    "4": "Carné de extranjería",
+    "6": "RUC",
+    "7": "Pasaporte",
+    "A": "Cédula diplomática",
+}
+
+# Catálogo 05: tributos
+TRIBUTOS = {
+    "1000": ("IGV", "VAT"),
+    "9995": ("EXP", "FRE"),
+    "9997": ("EXO", "VAT"),
+    "9998": ("INAF", "FRE"),
+}
+
+# Catálogo 07: tipo de afectación del IGV
+AFECTACIONES = {
+    "10": ("Gravado - operación onerosa", "S", "1000"),
+    "20": ("Exonerado - operación onerosa", "E", "9997"),
+    "30": ("Inafecto - operación onerosa", "O", "9998"),
+    "40": ("Exportación de bienes", "G", "9995"),
+}
+
+UNIDADES = {
+    "NIU": "Unidad",
+    "ZZ": "Servicio",
+    "KGM": "Kilogramo",
+    "LTR": "Litro",
+    "MTR": "Metro",
+    "BX": "Caja",
+    "PK": "Paquete",
+}
+
+
+@dataclass(frozen=True)
+class Afectacion:
+    codigo: str
+    descripcion: str
+    categoria: str
+    tributo: str
+    tasa: Decimal
+
+    @property
+    def gravada(self) -> bool:
+        return self.codigo == "10"
+
+    @property
+    def exenta(self) -> bool:
+        return not self.gravada
+
+
+def afectacion(codigo: str) -> Afectacion:
+    try:
+        descripcion, categoria, tributo = AFECTACIONES[codigo]
+    except KeyError:
+        raise ValueError(
+            f"Tipo de afectación '{codigo}' no soportado. "
+            f"Usa uno de: {', '.join(sorted(AFECTACIONES))}"
+        ) from None
+    return Afectacion(
+        codigo=codigo,
+        descripcion=descripcion,
+        categoria=categoria,
+        tributo=tributo,
+        tasa=TASA_IGV if codigo == "10" else Decimal("0"),
+    )

sunat_ubl-0.2.0/src/sunat_ubl/cdr.py

@@ -0,0 +1,90 @@
+"""Lectura del CDR (Constancia de Recepción) que devuelve SUNAT."""
+
+from __future__ import annotations
+
+import io
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from xml.etree import ElementTree as ET
+
+
+@dataclass(frozen=True)
+class Cdr:
+    codigo: str
+    descripcion: str
+    notas: tuple[str, ...] = ()
+    referencia: str | None = None
+    fecha: str | None = None
+    hash: str | None = None
+    identificador: str | None = None
+
+    @property
+    def aceptado(self) -> bool:
+        return self.codigo == "0"
+
+    @property
+    def observado(self) -> bool:
+        """Aceptado, pero con observaciones que conviene revisar."""
+        return self.aceptado and bool(self.notas)
+
+    @property
+    def rechazado(self) -> bool:
+        return not self.aceptado
+
+
+def _local(etiqueta: str) -> str:
+    return etiqueta.rsplit("}", 1)[-1]
+
+
+def _texto(raiz: ET.Element, nombre: str) -> str | None:
+    for elemento in raiz.iter():
+        if _local(elemento.tag) == nombre and elemento.text:
+            return elemento.text.strip()
+    return None
+
+
+def _hijo_directo(raiz: ET.Element, nombre: str) -> str | None:
+    for elemento in list(raiz):
+        if _local(elemento.tag) == nombre and elemento.text:
+            return elemento.text.strip()
+    return None
+
+
+def _textos(raiz: ET.Element, nombre: str) -> tuple[str, ...]:
+    return tuple(
+        elemento.text.strip()
+        for elemento in raiz.iter()
+        if _local(elemento.tag) == nombre and elemento.text and elemento.text.strip()
+    )
+
+
+def _extraer_xml(datos: bytes) -> bytes:
+    if datos[:2] != b"PK":
+        return datos
+    with zipfile.ZipFile(io.BytesIO(datos)) as archivo:
+        xmls = [n for n in archivo.namelist() if n.lower().endswith(".xml")]
+        if not xmls:
+            raise ValueError("El ZIP no contiene ningún archivo XML")
+        return archivo.read(xmls[0])
+
+
+def leer_cdr(origen: bytes | str | Path) -> Cdr:
+    """Parsea el CDR desde bytes, un ZIP o un XML suelto."""
+    if isinstance(origen, (str, Path)):
+        datos = Path(origen).read_bytes()
+    else:
+        datos = origen
+    raiz = ET.fromstring(_extraer_xml(datos))
+    codigo = _texto(raiz, "ResponseCode")
+    if codigo is None:
+        raise ValueError("El XML no parece un CDR: falta cbc:ResponseCode")
+    return Cdr(
+        codigo=codigo,
+        descripcion=_texto(raiz, "Description") or "",
+        notas=_textos(raiz, "Note"),
+        referencia=_texto(raiz, "ReferenceID"),
+        fecha=_hijo_directo(raiz, "IssueDate"),
+        hash=_texto(raiz, "DigestValue"),
+        identificador=_hijo_directo(raiz, "ID"),
+    )