openubl 0.1.0__py3-none-any.whl

openubl/__init__.py

@@ -0,0 +1,3 @@
+"""openUBL - Peruvian SUNAT Electronic Documents Library."""
+
+__version__ = "0.1.0"

openubl/api/__init__.py

@@ -0,0 +1 @@
+"""openUBL API package."""

openubl/api/router.py

@@ -0,0 +1,186 @@
+"""
+FastAPI router for openUBL REST API.
+"""
+from fastapi import APIRouter, Query, HTTPException
+from openubl import __version__
+
+from ..models import (
+    Invoice, CreditNote, DebitNote, VoidedDocuments,
+    SummaryDocuments, Perception, Retention,
+)
+from ..enricher import ContentEnricher
+from ..renderer import (
+    render_invoice, render_credit_note, render_debit_note,
+    render_voided_documents, render_summary_documents,
+    render_perception, render_retention,
+)
+from ..signer import sign_ubl_xml
+from ..validator import SunatValidator
+
+
+router = APIRouter()
+validator = SunatValidator()
+
+
+@router.get("/version")
+def get_version():
+    """Return the current API version.
+
+    Returns:
+        200: `{"version": "..."}` with the current API version.
+    """
+    return {"version": __version__}
+
+
+def _validate_xml(xml_string: str, doc_type: str) -> list[str]:
+    """Run SUNAT validation on rendered XML."""
+    if doc_type == "invoice":
+        return validator.validate_invoice(xml_string)
+    elif doc_type == "credit_note":
+        return validator.validate_credit_note(xml_string)
+    elif doc_type == "voided":
+        return validator.validate_voided_documents(xml_string)
+    return []
+
+
+@router.post("/invoice/create")
+def create_invoice(doc: Invoice, validate: bool = Query(default=True)):
+    """Generate an Invoice XML document.
+
+    The `validate` query parameter controls SUNAT validation and defaults to `true`.
+
+    Returns:
+        200: `{"xml": "..."}` with the generated XML.
+        422: Validation failed or the request body is invalid.
+    """
+    enricher = ContentEnricher()
+    enricher.enrich(doc)
+    xml = render_invoice(doc)
+    if validate:
+        errors = _validate_xml(xml, "invoice")
+        if errors:
+            raise HTTPException(status_code=422, detail=errors)
+    return {"xml": xml}
+
+
+@router.post("/credit-note/create")
+def create_credit_note(doc: CreditNote, validate: bool = Query(default=True)):
+    """Generate a CreditNote XML document.
+
+    The `validate` query parameter controls SUNAT validation and defaults to `true`.
+
+    Returns:
+        200: `{"xml": "..."}` with the generated XML.
+        422: Validation failed or the request body is invalid.
+    """
+    enricher = ContentEnricher()
+    enricher.enrich(doc)
+    xml = render_credit_note(doc)
+    if validate:
+        errors = _validate_xml(xml, "credit_note")
+        if errors:
+            raise HTTPException(status_code=422, detail=errors)
+    return {"xml": xml}
+
+
+@router.post("/debit-note/create")
+def create_debit_note(doc: DebitNote, validate: bool = Query(default=True)):
+    """Generate a DebitNote XML document.
+
+    The `validate` query parameter controls SUNAT validation and defaults to `true`.
+
+    Returns:
+        200: `{"xml": "..."}` with the generated XML.
+        422: Validation failed or the request body is invalid.
+    """
+    enricher = ContentEnricher()
+    enricher.enrich(doc)
+    xml = render_debit_note(doc)
+    if validate:
+        errors = _validate_xml(xml, "credit_note")
+        if errors:
+            raise HTTPException(status_code=422, detail=errors)
+    return {"xml": xml}
+
+
+@router.post("/voided-documents/create")
+def create_voided_documents(doc: VoidedDocuments, validate: bool = Query(default=True)):
+    """Generate a VoidedDocuments XML document.
+
+    The `validate` query parameter controls SUNAT validation and defaults to `true`.
+
+    Returns:
+        200: `{"xml": "..."}` with the generated XML.
+        422: Validation failed or the request body is invalid.
+    """
+    enricher = ContentEnricher()
+    enricher.enrich(doc)
+    xml = render_voided_documents(doc)
+    if validate:
+        errors = _validate_xml(xml, "voided")
+        if errors:
+            raise HTTPException(status_code=422, detail=errors)
+    return {"xml": xml}
+
+
+@router.post("/summary-documents/create")
+def create_summary_documents(doc: SummaryDocuments, validate: bool = Query(default=True)):
+    """Generate a SummaryDocuments XML document.
+
+    The `validate` query parameter controls SUNAT validation and defaults to `true`.
+
+    Returns:
+        200: `{"xml": "..."}` with the generated XML.
+        422: Validation failed or the request body is invalid.
+    """
+    xml = render_summary_documents(doc)
+    return {"xml": xml}
+
+
+@router.post("/perception/create")
+def create_perception(doc: Perception, validate: bool = Query(default=True)):
+    """Generate a Perception XML document.
+
+    The `validate` query parameter controls SUNAT validation and defaults to `true`.
+
+    Returns:
+        200: `{"xml": "..."}` with the generated XML.
+        422: Validation failed or the request body is invalid.
+    """
+    xml = render_perception(doc)
+    return {"xml": xml}
+
+
+@router.post("/retention/create")
+def create_retention(doc: Retention, validate: bool = Query(default=True)):
+    """Generate a Retention XML document.
+
+    The `validate` query parameter controls SUNAT validation and defaults to `true`.
+
+    Returns:
+        200: `{"xml": "..."}` with the generated XML.
+        422: Validation failed or the request body is invalid.
+    """
+    xml = render_retention(doc)
+    return {"xml": xml}
+
+
+@router.post("/sign")
+def sign_xml(payload: dict):
+    """Sign an arbitrary UBL XML document with a PEM certificate and key.
+
+    Required body fields:
+        - `xml`: The XML string to sign.
+        - `cert_pem`: The PEM-encoded certificate.
+        - `key_pem`: The PEM-encoded private key.
+        - `signature_id`: The signature ID (defaults to `SignSUNAT`).
+
+    Returns:
+        200: `{"signed_xml": "..."}` with the signed XML.
+    """
+    xml = payload.get("xml", "")
+    cert_pem = payload.get("cert_pem", "")
+    key_pem = payload.get("key_pem", "")
+    signature_id = payload.get("signature_id", "SignSUNAT")
+    signed = sign_ubl_xml(xml, cert_pem, key_pem, signature_id)
+    return {"signed_xml": signed}

openubl/enricher.py

@@ -0,0 +1,68 @@
+"""
+ContentEnricher - Auto-calculates tax fields and totals.
+Based on XBuilder Java ContentEnricher pattern.
+
+RS N° 300-2014/SUNAT, Anexo 1:
+- IGV: 18% (Ley N° 30296)
+- ICBPER: S/ 0.20 (Ley N° 30830)
+"""
+from datetime import date
+from decimal import Decimal, ROUND_HALF_UP
+
+from .models.defaults import DateProvider, Defaults
+from .models.invoice import DocumentoVentaDetalle, Invoice
+from .models.credit_note import CreditNote
+from .models.debit_note import DebitNote
+from .models.voided import VoidedDocuments
+
+
+def _round(value: Decimal) -> Decimal:
+    """Round to 2 decimal places using HALF_UP."""
+    return value.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+
+class ContentEnricher:
+    """Enriches documents with auto-calculated tax fields."""
+    
+    def __init__(self, defaults: Defaults | None = None, date_provider: DateProvider | None = None):
+        self.defaults = defaults or Defaults()
+        self.date_provider = date_provider or DateProvider()
+    
+    def enrich(self, doc):
+        """Enrich a document in-place."""
+        if isinstance(doc, (Invoice, CreditNote, DebitNote)):
+            self._enrich_invoice_like(doc)
+        elif isinstance(doc, VoidedDocuments):
+            self._enrich_voided(doc)
+        # Summary, Perception, Retention: no enrichment needed
+    
+    def _enrich_invoice_like(self, doc: Invoice | CreditNote | DebitNote):
+        """Enrich invoice, credit note, or debit note."""
+        if doc.fechaEmision is None:
+            doc.fechaEmision = self.date_provider.now()
+        
+        for detalle in doc.detalles:
+            self._enrich_detalle(detalle)
+        
+        doc.valorVentaTotal = _round(sum(d.valorVenta or Decimal("0") for d in doc.detalles))
+        doc.igvTotal = _round(sum(d.igv or Decimal("0") for d in doc.detalles))
+        doc.importeTotal = _round(doc.valorVentaTotal + doc.igvTotal)
+    
+    def _enrich_detalle(self, detalle: DocumentoVentaDetalle):
+        """Enrich a single line item."""
+        if detalle.valorVenta is None:
+            detalle.valorVenta = _round(detalle.cantidad * detalle.precio)
+        
+        if detalle.igv is None:
+            if detalle.tipoAfectacionIGV == "10":  # Gravado
+                detalle.igv = _round(detalle.valorVenta * self.defaults.igvTasa)
+            else:
+                detalle.igv = Decimal("0")
+        
+        if detalle.precioVenta is None:
+            detalle.precioVenta = _round(detalle.valorVenta + detalle.igv)
+    
+    def _enrich_voided(self, doc: VoidedDocuments):
+        """Enrich voided documents."""
+        if doc.fechaEmision is None:
+            doc.fechaEmision = self.date_provider.now()

openubl/main.py

@@ -0,0 +1,8 @@
+"""
+FastAPI application for openUBL.
+"""
+from fastapi import FastAPI
+from .api.router import router
+
+app = FastAPI(title="openUBL", version="0.1.0")
+app.include_router(router, prefix="/api/v1")

openubl/models/__init__.py

@@ -0,0 +1,61 @@
+"""openUBL models package."""
+
+from .catalog import (
+    Catalog1,
+    Catalog2,
+    Catalog5,
+    Catalog6,
+    Catalog7,
+    Catalog16,
+    Catalog19,
+    Catalog22,
+    Catalog23,
+)
+from .common import Address, Cliente, Proveedor
+from .defaults import DateProvider, Defaults
+from .invoice import DocumentoVentaDetalle, Invoice
+from .credit_note import CreditNote
+from .debit_note import DebitNote
+from .voided import VoidedDocuments, VoidedDocumentsItem
+from .summary import (
+    Comprobante,
+    ComprobanteAfectado,
+    ComprobanteImpuestos,
+    ComprobanteValorVenta,
+    SummaryDocuments,
+    SummaryDocumentsItem,
+)
+from .perception import Perception, PercepcionRetencionOperacion
+from .retention import Retention
+
+__all__ = [
+    "Catalog1",
+    "Catalog2",
+    "Catalog5",
+    "Catalog6",
+    "Catalog7",
+    "Catalog16",
+    "Catalog19",
+    "Catalog22",
+    "Catalog23",
+    "Address",
+    "Cliente",
+    "Proveedor",
+    "DateProvider",
+    "Defaults",
+    "DocumentoVentaDetalle",
+    "Invoice",
+    "CreditNote",
+    "DebitNote",
+    "VoidedDocuments",
+    "VoidedDocumentsItem",
+    "Comprobante",
+    "ComprobanteAfectado",
+    "ComprobanteImpuestos",
+    "ComprobanteValorVenta",
+    "SummaryDocuments",
+    "SummaryDocumentsItem",
+    "Perception",
+    "PercepcionRetencionOperacion",
+    "Retention",
+]

openubl/models/catalog.py

@@ -0,0 +1,93 @@
+"""
+SUNAT Catalog constants for electronic documents.
+Based on RS N° 300-2014/SUNAT and its annexes.
+"""
+from enum import Enum
+
+
+class Catalog1(str, Enum):
+    """Tipo de Comprobante - Catálogo N.° 01"""
+    FACTURA = "01"
+    BOLETA = "03"
+    NOTA_CREDITO = "07"
+    NOTA_DEBITO = "08"
+    GUIA_REMISION = "09"
+    COMPROBANTE_RETENCION = "20"
+    COMPROBANTE_PERCEPCION = "40"
+
+
+class Catalog6(str, Enum):
+    """Tipo de Documento de Identidad - Catálogo N.° 06"""
+    DOC_NO_DOMICILIADO = "0"
+    DNI = "1"
+    CE = "4"
+    RUC = "6"
+    PASAPORTE = "7"
+
+
+class Catalog7(str, Enum):
+    """Tipo de Afectación del IGV - Catálogo N.° 07"""
+    GRAVADO_OPERACION_ONEROSA = "10"
+    EXONERADO_OPERACION_ONEROSA = "20"
+    INAFECTO_OPERACION_ONEROSA = "30"
+
+
+class Catalog16(str, Enum):
+    """Tipo de Precio - Catálogo N.° 16"""
+    PRECIO_UNITARIO_INCLUYE_IGV = "01"
+    VALOR_REFERENCIAL_UNITARIO_EN_OPERACIONES_NO_ONEROSAS = "02"
+
+
+class Catalog19(str, Enum):
+    """Tipo de Operación - Resumen Diario - Catálogo N.° 19"""
+    ADICIONAR = "1"
+    MODIFICAR = "2"
+    ANULADO = "3"
+
+
+class Catalog22(str, Enum):
+    """Régimen de Percepción - Catálogo N.° 22"""
+    VENTA_INTERNA = "01"
+    ADQUISICION_COMBUSTIBLE = "02"
+    TASA_TRES = "03"
+
+
+class Catalog23(str, Enum):
+    """Régimen de Retención - Catálogo N.° 23"""
+    TASA_TRES = "01"
+    TASA_SEIS = "02"
+    TASA_MIXTA = "03"
+
+
+class Catalog2(str, Enum):
+    """Tipo de Moneda - Catálogo N.° 02"""
+    PEN = "PEN"
+    USD = "USD"
+    EUR = "EUR"
+
+
+class Catalog5(str, Enum):
+    """Tipo de Tributo - Catálogo N.° 05"""
+    IGV = "1000"
+    ISC = "2000"
+    EXPORTACION = "9995"
+    GRATUITAS = "9996"
+    EXONERADO = "9997"
+    INAFECTO = "9998"
+    OTROS_TRIBUTOS = "9999"
+    ICBPER = "7152"
+    IVAP = "1016"
+
+
+class Catalog20(str, Enum):
+    """Motivo de Traslado - Catálogo N.° 20"""
+    VENTA = "01"
+    COMPRA = "02"
+    VENTA_SUJETA_A_CONFIRMAR = "03"
+    TRASLADO_ENTRE_ESTABLECIMIENTOS = "04"
+    CONSIGNACION = "05"
+    DEVOLUCION = "06"
+    IMPORTACION = "08"
+    EXPORTACION = "09"
+    TRASLADO_EMISOR_ITINERANTE = "13"
+    OTROS = "14"

openubl/models/common.py

@@ -0,0 +1,46 @@
+"""
+Common models for electronic documents.
+Based on RS N° 300-2014/SUNAT - Sistema de Emisión Electrónica.
+"""
+from pydantic import BaseModel, Field
+
+
+class Address(BaseModel):
+    """Dirección según esquema UBL 2.1 de SUNAT."""
+    ubigeo: str | None = None
+    direccion: str | None = None
+    urbanizacion: str | None = None
+    provincia: str | None = None
+    departamento: str | None = None
+    distrito: str | None = None
+    codigoPais: str = "PE"
+
+
+class Proveedor(BaseModel):
+    """Datos del emisor del comprobante.
+    
+    RS N° 300-2014/SUNAT, Anexo 1:
+    - RUC del emisor: 11 dígitos numéricos (Catálogo N.° 06, valor 6)
+    - Razón social: obligatoria
+    """
+    ruc: str = Field(
+        min_length=11,
+        max_length=11,
+        pattern=r"^\d{11}$",
+        description="RUC del emisor - 11 dígitos numéricos",
+    )
+    razonSocial: str
+    nombreComercial: str | None = None
+    address: Address | None = None
+
+
+class Cliente(BaseModel):
+    """Datos del adquirente o usuario.
+    
+    RS N° 300-2014/SUNAT, Anexo 1:
+    - Tipo de documento: Catálogo N.° 06
+    - Número de documento: según tipo
+    """
+    nombre: str
+    numeroDocumentoIdentidad: str
+    tipoDocumentoIdentidad: str  # Catalog6 code

openubl/models/credit_note.py

@@ -0,0 +1,35 @@
+"""
+Credit Note model for SUNAT electronic invoicing.
+RS N° 300-2014/SUNAT - Nota de Crédito Electrónica (07).
+"""
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, Field
+
+from .common import Cliente, Proveedor
+from .invoice import DocumentoVentaDetalle
+
+
+class CreditNote(BaseModel):
+    """Nota de Crédito Electrónica - Tipo 07.
+    
+    RS N° 300-2014/SUNAT, Anexo 1:
+    - Serie: debe iniciar con B/C o F/E según tipo de documento afectado
+    - Debe referenciar el comprobante afectado
+    """
+    serie: str = Field(
+        pattern=r"^[BCbc][A-Za-z0-9]{2,3}$",
+        description="Serie de nota de crédito",
+    )
+    numero: int
+    comprobanteAfectadoSerieNumero: str
+    sustentoDescripcion: str
+    proveedor: Proveedor
+    cliente: Cliente
+    detalles: list[DocumentoVentaDetalle]
+    moneda: str = "PEN"
+    fechaEmision: date | None = None
+    igvTotal: Decimal | None = None
+    valorVentaTotal: Decimal | None = None
+    importeTotal: Decimal | None = None

openubl/models/debit_note.py

@@ -0,0 +1,35 @@
+"""
+Debit Note model for SUNAT electronic invoicing.
+RS N° 300-2014/SUNAT - Nota de Débito Electrónica (08).
+"""
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, Field
+
+from .common import Cliente, Proveedor
+from .invoice import DocumentoVentaDetalle
+
+
+class DebitNote(BaseModel):
+    """Nota de Débito Electrónica - Tipo 08.
+    
+    RS N° 300-2014/SUNAT, Anexo 1:
+    - Serie: debe iniciar con B/C o F/E según tipo de documento afectado
+    - Debe referenciar el comprobante afectado
+    """
+    serie: str = Field(
+        pattern=r"^[BCbc][A-Za-z0-9]{2,3}$",
+        description="Serie de nota de débito",
+    )
+    numero: int
+    comprobanteAfectadoSerieNumero: str
+    sustentoDescripcion: str
+    proveedor: Proveedor
+    cliente: Cliente
+    detalles: list[DocumentoVentaDetalle]
+    moneda: str = "PEN"
+    fechaEmision: date | None = None
+    igvTotal: Decimal | None = None
+    valorVentaTotal: Decimal | None = None
+    importeTotal: Decimal | None = None

openubl/models/defaults.py

@@ -0,0 +1,25 @@
+"""
+Default values for document generation.
+"""
+from decimal import Decimal
+
+from pydantic import BaseModel
+
+
+class Defaults(BaseModel):
+    """Valores por defecto para cálculos de impuestos.
+    
+    Ley N° 30296 - IGV tasa 18%
+    Ley N° 30830 - ICBPER tasa S/ 0.20
+    """
+    igvTasa: Decimal = Decimal("0.18")
+    icbTasa: Decimal = Decimal("0.2")
+
+
+class DateProvider:
+    """Proveedor de fechas para facilitar testing."""
+    
+    @staticmethod
+    def now():
+        from datetime import date
+        return date.today()

openubl/models/invoice.py

@@ -0,0 +1,53 @@
+"""
+Invoice model for SUNAT electronic invoicing.
+RS N° 300-2014/SUNAT - Factura Electrónica (01).
+"""
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, Field
+
+from .common import Cliente, Proveedor
+
+
+class DocumentoVentaDetalle(BaseModel):
+    """Línea de detalle de un documento de venta.
+    
+    RS N° 300-2014/SUNAT, Anexo 1:
+    - Descripción del bien o servicio
+    - Cantidad y unidad de medida (Catálogo N.° 03)
+    - Valor unitario (sin IGV)
+    - Tipo de afectación del IGV (Catálogo N.° 07)
+    """
+    descripcion: str
+    cantidad: Decimal
+    precio: Decimal
+    unidadMedida: str = "NIU"
+    tipoAfectacionIGV: str = "10"  # Catalog7 default: GRAVADO_OPERACION_ONEROSA
+    igv: Decimal | None = None
+    valorVenta: Decimal | None = None
+    precioVenta: Decimal | None = None
+
+
+class Invoice(BaseModel):
+    """Factura Electrónica - Tipo 01.
+    
+    RS N° 300-2014/SUNAT, Anexo 1:
+    - Serie: debe iniciar con F (factura) o B (boleta)
+    - Número: correlativo
+    - Tipo de operación: Catálogo N.° 51, default 0101 (Venta interna)
+    """
+    serie: str = Field(
+        pattern=r"^[FBfb][A-Za-z0-9]{2,3}$",
+        description="Serie de factura (F001) o boleta (B001)",
+    )
+    numero: int
+    proveedor: Proveedor
+    cliente: Cliente
+    detalles: list[DocumentoVentaDetalle]
+    moneda: str = "PEN"
+    fechaEmision: date | None = None
+    igvTotal: Decimal | None = None
+    valorVentaTotal: Decimal | None = None
+    importeTotal: Decimal | None = None
+    tipoOperacion: str = "0101"  # Default: Venta interna

openubl/models/perception.py

@@ -0,0 +1,48 @@
+"""
+Perception model for SUNAT electronic invoicing.
+RS N° 274-2015/SUNAT - Comprobante de Percepción Electrónico (40).
+"""
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, Field
+
+from .common import Cliente, Proveedor
+
+
+class ComprobanteAfectado(BaseModel):
+    """Comprobante afectado por la percepción."""
+    tipoComprobante: str
+    serieNumero: str
+    fechaEmision: date
+    importeTotal: Decimal
+    moneda: str
+
+
+class PercepcionRetencionOperacion(BaseModel):
+    """Operación de percepción."""
+    numeroOperacion: int
+    fechaOperacion: date
+    importeOperacion: Decimal
+    comprobante: ComprobanteAfectado
+
+class Perception(BaseModel):
+    """Comprobante de Percepción Electrónico - Tipo 40.
+    
+    RS N° 274-2015/SUNAT, Anexo 1:
+    - Serie: P### (P001, P002, etc.)
+    - Régimen: Catálogo N.° 22
+    """
+    serie: str = Field(
+        pattern=r"^P\d{3}$",
+        description="Serie de percepción (P###)",
+    )
+    numero: int
+    fechaEmision: date
+    proveedor: Proveedor
+    cliente: Cliente
+    importeTotalPercibido: Decimal
+    importeTotalCobrado: Decimal
+    tipoRegimen: str  # Catalog22
+    tipoRegimenPorcentaje: Decimal
+    operaciones: list[PercepcionRetencionOperacion]