eqinvoice 1.1.0__py3-none-any.whl

eqinvoice/__init__.py

@@ -0,0 +1,97 @@
+from eqinvoice.access_key import access_key, check_digit, issue_date
+from eqinvoice.document import build, rimpe_legend, validate
+from eqinvoice.errors import (
+    CredentialProblem,
+    CredentialRefused,
+    SriUnavailable,
+    VoucherInvalid,
+)
+from eqinvoice.model import (
+    Buyer,
+    BuyerKind,
+    Environment,
+    Issued,
+    Issuer,
+    Line,
+    Modified,
+    Payment,
+    TaxGroup,
+    Voucher,
+    VoucherKind,
+)
+from eqinvoice.pricing import cents, price_line
+from eqinvoice.record import read, read_voucher
+from eqinvoice.registry import (
+    Establishment,
+    Registry,
+    SimulatedRegistry,
+    SriRegistry,
+    Taxpayer,
+)
+from eqinvoice.service import (
+    Authorization,
+    Message,
+    Reception,
+    SimulatedSri,
+    Sri,
+    SriWebServices,
+)
+from eqinvoice.signature import (
+    Credential,
+    SignatureDetails,
+    details,
+    load_credential,
+    read_credential,
+    sign,
+    sign_voucher,
+    simulated_credential,
+    usable,
+)
+
+__all__ = [
+    "Authorization",
+    "Buyer",
+    "BuyerKind",
+    "Credential",
+    "CredentialProblem",
+    "CredentialRefused",
+    "Environment",
+    "Establishment",
+    "Issued",
+    "Issuer",
+    "Line",
+    "Message",
+    "Modified",
+    "Payment",
+    "Reception",
+    "Registry",
+    "SignatureDetails",
+    "SimulatedRegistry",
+    "SimulatedSri",
+    "Sri",
+    "SriRegistry",
+    "SriUnavailable",
+    "SriWebServices",
+    "TaxGroup",
+    "Taxpayer",
+    "Voucher",
+    "VoucherInvalid",
+    "VoucherKind",
+    "access_key",
+    "build",
+    "cents",
+    "check_digit",
+    "details",
+    "issue_date",
+    "load_credential",
+    "price_line",
+    "read",
+    "read_credential",
+    "read_voucher",
+    "rimpe_legend",
+    "sign",
+    "sign_voucher",
+    "simulated_credential",
+    "usable",
+    "validate",
+]

eqinvoice/access_key.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import secrets
+from datetime import date, datetime
+
+from eqinvoice.model import Environment, VoucherKind
+from eqinvoice.protocol import (
+    CLOCK,
+    DOCUMENT_CODES,
+    ENVIRONMENT_CODES,
+    NORMAL_EMISSION,
+)
+
+WEIGHTS = (2, 3, 4, 5, 6, 7)
+MODULUS = 11
+NUMERIC_CODE_DIGITS = 8
+
+
+def check_digit(digits: str) -> str:
+    total = sum(
+        int(digit) * WEIGHTS[index % len(WEIGHTS)] for index, digit in enumerate(reversed(digits))
+    )
+    remainder = MODULUS - total % MODULUS
+    return {MODULUS: "0", MODULUS - 1: "1"}.get(remainder, str(remainder))
+
+
+def access_key(
+    issued_on: date,
+    kind: VoucherKind,
+    ruc: str,
+    environment: Environment,
+    establishment: str,
+    point: str,
+    sequential: int,
+) -> str:
+    """The clave de acceso, with a fresh numeric code and its check digit."""
+    numeric = f"{secrets.randbelow(10**NUMERIC_CODE_DIGITS):0{NUMERIC_CODE_DIGITS}d}"
+    body = (
+        f"{issued_on:%d%m%Y}{DOCUMENT_CODES[kind]}{ruc}{ENVIRONMENT_CODES[environment]}"
+        f"{establishment}{point}{sequential:09d}{numeric}{NORMAL_EMISSION}"
+    )
+    return body + check_digit(body)
+
+
+def issue_date(now: datetime) -> date:
+    return now.astimezone(CLOCK).date()

eqinvoice/document.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from functools import cache
+
+from lxml import etree
+
+from eqinvoice.errors import VoucherInvalid
+from eqinvoice.model import ZERO, Issuer, Voucher, VoucherKind
+from eqinvoice.protocol import (
+    BUYER_CODES,
+    CODE_TAGS,
+    CURRENCY_NAME,
+    DATE_FORMAT,
+    DOCUMENT_CODES,
+    EMAIL_FIELD,
+    ENVIRONMENT_CODES,
+    INFO,
+    MOST_EXTRA_FIELDS,
+    NO,
+    NORMAL_EMISSION,
+    PARSER,
+    RIMPE_TYPE,
+    ROOTS,
+    SCHEMA_DIR,
+    SCHEMAS,
+    SYSTEM_PROVIDER_FIELD,
+    VAT_TAX,
+    VERSION,
+    VOUCHER_ID,
+    XSD_NS,
+    YES,
+    buyer_shown,
+)
+
+
+def money(amount: Decimal) -> str:
+    return f"{amount:.2f}"
+
+
+def _six(amount: Decimal) -> str:
+    return f"{amount:.6f}"
+
+
+def _add(parent: etree._Element, tag: str, text: str | None = None) -> etree._Element:
+    child = etree.SubElement(parent, tag)
+    if text is not None:
+        child.text = text
+    return child
+
+
+def _optional(parent: etree._Element, tag: str, text: str | None) -> None:
+    if text:
+        _add(parent, tag, text)
+
+
+def _info_tributaria(root: etree._Element, voucher: Voucher, issuer: Issuer) -> None:
+    info = _add(root, "infoTributaria")
+    _add(info, "ambiente", ENVIRONMENT_CODES[voucher.environment])
+    _add(info, "tipoEmision", NORMAL_EMISSION)
+    _add(info, "razonSocial", issuer.legal_name)
+    _optional(info, "nombreComercial", issuer.trade_name)
+    _add(info, "ruc", issuer.ruc)
+    _add(info, "claveAcceso", voucher.access_key)
+    _add(info, "codDoc", DOCUMENT_CODES[voucher.kind])
+    _add(info, "estab", voucher.establishment)
+    _add(info, "ptoEmi", voucher.point)
+    _add(info, "secuencial", f"{voucher.sequential:09d}")
+    _add(info, "dirMatriz", issuer.head_office_address)
+    _optional(info, "agenteRetencion", issuer.withholding_agent)
+    if issuer.rimpe:
+        _add(info, RIMPE_TYPE, rimpe_legend())
+
+
+def _buyer(info: etree._Element, voucher: Voucher) -> None:
+    buyer = voucher.buyer
+    name, identification = buyer_shown(buyer.kind, buyer.name, buyer.identification)
+    _add(info, "tipoIdentificacionComprador", BUYER_CODES[buyer.kind])
+    _add(info, "razonSocialComprador", name)
+    _add(info, "identificacionComprador", identification)
+
+
+def _taxes(info: etree._Element, voucher: Voucher) -> None:
+    totals = _add(info, "totalConImpuestos")
+    for group in voucher.tax_groups:
+        tax = _add(totals, "totalImpuesto")
+        _add(tax, "codigo", VAT_TAX)
+        _add(tax, "codigoPorcentaje", group.code)
+        _add(tax, "baseImponible", money(group.base))
+        _add(tax, "valor", money(group.vat))
+
+
+def _accounts(info: etree._Element, issuer: Issuer) -> None:
+    _add(info, "obligadoContabilidad", YES if issuer.keeps_accounts else NO)
+
+
+def _invoice_info(root: etree._Element, voucher: Voucher, issuer: Issuer) -> None:
+    info = _add(root, INFO[VoucherKind.INVOICE])
+    _add(info, "fechaEmision", voucher.issued_on.strftime(DATE_FORMAT))
+    _add(info, "dirEstablecimiento", voucher.establishment_address)
+    _optional(info, "contribuyenteEspecial", issuer.special_taxpayer)
+    _accounts(info, issuer)
+    _buyer(info, voucher)
+    _add(info, "totalSinImpuestos", money(voucher.subtotal))
+    _add(info, "totalDescuento", money(voucher.discount))
+    _taxes(info, voucher)
+    _add(info, "propina", money(ZERO))
+    _add(info, "importeTotal", money(voucher.total))
+    _add(info, "moneda", CURRENCY_NAME)
+    payments = _add(info, "pagos")
+    for payment in voucher.payment_forms:
+        paid = _add(payments, "pago")
+        _add(paid, "formaPago", payment.form)
+        _add(paid, "total", money(payment.amount))
+
+
+def _credit_info(root: etree._Element, voucher: Voucher, issuer: Issuer) -> None:
+    modified = voucher.modified
+    if modified is None:
+        raise VoucherInvalid("A credit note names the invoice it modifies")
+    info = _add(root, INFO[VoucherKind.CREDIT_NOTE])
+    _add(info, "fechaEmision", voucher.issued_on.strftime(DATE_FORMAT))
+    _add(info, "dirEstablecimiento", voucher.establishment_address)
+    _buyer(info, voucher)
+    _optional(info, "contribuyenteEspecial", issuer.special_taxpayer)
+    _accounts(info, issuer)
+    _add(info, "codDocModificado", DOCUMENT_CODES[VoucherKind.INVOICE])
+    _add(info, "numDocModificado", modified.number)
+    _add(info, "fechaEmisionDocSustento", modified.issued_on.strftime(DATE_FORMAT))
+    _add(info, "totalSinImpuestos", money(voucher.subtotal))
+    _add(info, "valorModificacion", money(voucher.total))
+    _add(info, "moneda", CURRENCY_NAME)
+    _taxes(info, voucher)
+    _add(info, "motivo", modified.reason)
+
+
+def _details(root: etree._Element, voucher: Voucher) -> None:
+    details = _add(root, "detalles")
+    for line in voucher.lines:
+        detail = _add(details, "detalle")
+        _add(detail, CODE_TAGS[voucher.kind], line.code)
+        _add(detail, "descripcion", line.description)
+        _add(detail, "cantidad", _six(line.quantity))
+        _add(detail, "precioUnitario", _six(line.unit_price))
+        _add(detail, "descuento", money(line.discount))
+        _add(detail, "precioTotalSinImpuesto", money(line.subtotal))
+        tax = _add(_add(detail, "impuestos"), "impuesto")
+        _add(tax, "codigo", VAT_TAX)
+        _add(tax, "codigoPorcentaje", line.rate_code)
+        _add(tax, "tarifa", money(line.rate_percentage))
+        _add(tax, "baseImponible", money(line.subtotal))
+        _add(tax, "valor", money(line.vat))
+
+
+def _extra(root: etree._Element, voucher: Voucher, issuer: Issuer) -> None:
+    fields = list(voucher.extra)
+    if voucher.buyer.email:
+        fields.insert(0, (EMAIL_FIELD, voucher.buyer.email))
+    if issuer.system_provider_ruc:
+        fields.append((SYSTEM_PROVIDER_FIELD, issuer.system_provider_ruc))
+    if not fields:
+        return
+    extra = _add(root, "infoAdicional")
+    for name, value in fields[:MOST_EXTRA_FIELDS]:
+        _add(extra, "campoAdicional", value).set("nombre", name)
+
+
+def build(voucher: Voucher, issuer: Issuer) -> etree._Element:
+    root = etree.Element(ROOTS[voucher.kind], id=VOUCHER_ID, version=VERSION)
+    _info_tributaria(root, voucher, issuer)
+    if voucher.kind == VoucherKind.INVOICE:
+        _invoice_info(root, voucher, issuer)
+    else:
+        _credit_info(root, voucher, issuer)
+    _details(root, voucher)
+    _extra(root, voucher, issuer)
+    return root
+
+
+@cache
+def _schema_document(kind: VoucherKind) -> etree._ElementTree:
+    return etree.parse(str(SCHEMA_DIR / SCHEMAS[kind]), PARSER)
+
+
+@cache
+def _schema(kind: VoucherKind) -> etree.XMLSchema:
+    return etree.XMLSchema(_schema_document(kind))
+
+
+@cache
+def rimpe_legend() -> str:
+    pattern = _schema_document(VoucherKind.INVOICE).find(
+        f"{{{XSD_NS}}}simpleType[@name='{RIMPE_TYPE}']/{{{XSD_NS}}}restriction/{{{XSD_NS}}}pattern"
+    )
+    if pattern is None:
+        raise VoucherInvalid("The SRI's schema no longer fixes the RIMPE legend")
+    return str(pattern.get("value"))
+
+
+def validate(kind: VoucherKind, document: bytes) -> None:
+    schema = _schema(kind)
+    if not schema.validate(etree.fromstring(document, PARSER)):
+        raise VoucherInvalid("; ".join(str(error.message) for error in schema.error_log))

eqinvoice/errors.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class SriUnavailable(RuntimeError):
+    """The SRI could not be reached or failed on its side; the same voucher can be sent again."""
+
+
+class VoucherInvalid(ValueError):
+    """The voucher does not satisfy the SRI's schema, so sending it would only be returned."""
+
+
+class CredentialProblem(StrEnum):
+    MISSING = "missing"
+    UNREADABLE = "unreadable"
+    OUT_OF_DATE = "out_of_date"
+
+
+class CredentialRefused(RuntimeError):
+    def __init__(self, problem: CredentialProblem, reason: str) -> None:
+        super().__init__(reason)
+        self.problem = problem

eqinvoice/labels/es.json

@@ -0,0 +1,65 @@
+{
+  "documents": {
+    "invoice": "FACTURA",
+    "credit_note": "NOTA DE CRÉDITO"
+  },
+  "ruc": "R.U.C.",
+  "number": "No.",
+  "authorizationNumber": "NÚMERO DE AUTORIZACIÓN",
+  "authorizedAt": "FECHA Y HORA DE AUTORIZACIÓN",
+  "environment": "AMBIENTE",
+  "environments": {
+    "test": "PRUEBAS",
+    "production": "PRODUCCIÓN"
+  },
+  "emission": "EMISIÓN",
+  "normalEmission": "NORMAL",
+  "accessKey": "CLAVE DE ACCESO",
+  "headOffice": "Dirección Matriz",
+  "branch": "Dirección Sucursal",
+  "specialTaxpayer": "Contribuyente Especial Nro.",
+  "keepsAccounts": "OBLIGADO A LLEVAR CONTABILIDAD",
+  "yes": "SI",
+  "no": "NO",
+  "withholdingAgent": "Agente de Retención Resolución No.",
+  "buyerName": "Razón Social / Nombres y Apellidos",
+  "buyerId": "Identificación",
+  "issuedOn": "Fecha Emisión",
+  "modified": "Comprobante que se modifica",
+  "modifiedIssuedOn": "Fecha Emisión (Comprobante a modificar)",
+  "reason": "Razón de Modificación",
+  "columns": {
+    "code": "Cod. Principal",
+    "quantity": "Cantidad",
+    "description": "Descripción",
+    "unitPrice": "Precio Unitario",
+    "discount": "Descuento",
+    "total": "Precio Total"
+  },
+  "extra": "Información Adicional",
+  "paymentForm": "Forma de pago",
+  "value": "Valor",
+  "paymentForms": {
+    "01": "SIN UTILIZACIÓN DEL SISTEMA FINANCIERO",
+    "15": "COMPENSACIÓN DE DEUDAS",
+    "16": "TARJETA DE DÉBITO",
+    "17": "DINERO ELECTRÓNICO",
+    "18": "TARJETA PREPAGO",
+    "19": "TARJETA DE CRÉDITO",
+    "20": "OTROS CON UTILIZACIÓN DEL SISTEMA FINANCIERO",
+    "21": "ENDOSO DE TÍTULOS"
+  },
+  "subtotalRated": "SUBTOTAL {{rate}}%",
+  "subtotalUnrated": {
+    "0": "SUBTOTAL 0%",
+    "6": "SUBTOTAL NO OBJETO DE IVA",
+    "7": "SUBTOTAL EXENTO DE IVA"
+  },
+  "subtotal": "SUBTOTAL SIN IMPUESTOS",
+  "ice": "ICE",
+  "irbpnr": "IRBPNR",
+  "tip": "PROPINA",
+  "discount": "TOTAL DESCUENTO",
+  "vatRated": "IVA {{rate}}%",
+  "total": "VALOR TOTAL"
+}

eqinvoice/model.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from enum import StrEnum
+
+ZERO = Decimal("0")
+
+
+class VoucherKind(StrEnum):
+    INVOICE = "invoice"
+    CREDIT_NOTE = "credit_note"
+
+
+class Environment(StrEnum):
+    TEST = "test"
+    PRODUCTION = "production"
+
+
+class BuyerKind(StrEnum):
+    RUC = "ruc"
+    CEDULA = "cedula"
+    PASSPORT = "passport"
+    FINAL_CONSUMER = "final_consumer"
+
+
+@dataclass(frozen=True)
+class Issuer:
+    legal_name: str
+    ruc: str
+    head_office_address: str
+    keeps_accounts: bool
+    trade_name: str | None = None
+    special_taxpayer: str | None = None
+    withholding_agent: str | None = None
+    rimpe: bool = False
+    system_provider_ruc: str | None = None
+
+
+@dataclass(frozen=True)
+class Buyer:
+    """Whom the voucher is for; a final consumer carries neither identification nor name."""
+
+    kind: BuyerKind
+    identification: str | None = None
+    name: str | None = None
+    email: str | None = None
+
+
+@dataclass(frozen=True)
+class Line:
+    """One line, already split: every amount before IVA, then the IVA itself."""
+
+    code: str
+    description: str
+    quantity: Decimal
+    unit_price: Decimal
+    discount: Decimal
+    subtotal: Decimal
+    vat: Decimal
+    rate_code: str
+    rate_percentage: Decimal
+
+
+@dataclass(frozen=True)
+class Payment:
+    """Part of what an invoice was paid with: the SRI's payment form code and the amount."""
+
+    form: str
+    amount: Decimal
+
+
+@dataclass(frozen=True)
+class Modified:
+    number: str
+    issued_on: date
+    reason: str
+
+
+@dataclass(frozen=True)
+class TaxGroup:
+    code: str
+    base: Decimal
+    vat: Decimal
+    rate: Decimal
+
+
+@dataclass(frozen=True)
+class Voucher:
+    kind: VoucherKind
+    environment: Environment
+    access_key: str
+    establishment: str
+    point: str
+    sequential: int
+    establishment_address: str
+    issued_on: date
+    buyer: Buyer
+    lines: tuple[Line, ...]
+    payments: tuple[Payment, ...] = ()
+    modified: Modified | None = None
+    extra: tuple[tuple[str, str], ...] = ()
+
+    @property
+    def number(self) -> str:
+        return f"{self.establishment}-{self.point}-{self.sequential:09d}"
+
+    @property
+    def subtotal(self) -> Decimal:
+        return sum((line.subtotal for line in self.lines), ZERO)
+
+    @property
+    def discount(self) -> Decimal:
+        return sum((line.discount for line in self.lines), ZERO)
+
+    @property
+    def vat(self) -> Decimal:
+        return sum((line.vat for line in self.lines), ZERO)
+
+    @property
+    def total(self) -> Decimal:
+        return self.subtotal + self.vat
+
+    @property
+    def tax_groups(self) -> tuple[TaxGroup, ...]:
+        """The lines added up per IVA rate, in the order the rates first appear."""
+        groups: dict[str, TaxGroup] = {}
+        for line in self.lines:
+            held = groups.get(line.rate_code)
+            base, vat = (held.base, held.vat) if held else (ZERO, ZERO)
+            groups[line.rate_code] = TaxGroup(
+                line.rate_code, base + line.subtotal, vat + line.vat, line.rate_percentage
+            )
+        return tuple(groups.values())
+
+    @property
+    def payment_forms(self) -> tuple[Payment, ...]:
+        """The payments added up per form, in the order the forms first appear."""
+        forms: dict[str, Decimal] = {}
+        for payment in self.payments:
+            forms[payment.form] = forms.get(payment.form, ZERO) + payment.amount
+        return tuple(Payment(form, amount) for form, amount in forms.items())
+
+
+@dataclass(frozen=True)
+class Issued:
+    voucher: Voucher
+    issuer: Issuer
+    authorized_at: datetime
+    authorization_number: str
+    total: Decimal
+    ice: Decimal = ZERO
+    irbpnr: Decimal = ZERO
+    tip: Decimal | None = None

eqinvoice/pricing.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from decimal import ROUND_HALF_UP, Decimal
+
+from eqinvoice.errors import VoucherInvalid
+from eqinvoice.model import ZERO, Line
+from eqinvoice.protocol import VAT_RATES
+
+CENT = Decimal("0.01")
+HUNDRED = Decimal("100")
+
+
+def cents(amount: Decimal) -> Decimal:
+    return amount.quantize(CENT, ROUND_HALF_UP)
+
+
+def price_line(
+    code: str,
+    description: str,
+    quantity: Decimal,
+    unit_price: Decimal,
+    rate_code: str,
+    discount: Decimal = ZERO,
+) -> Line:
+    rate = VAT_RATES.get(rate_code)
+    if rate is None:
+        raise VoucherInvalid(f"The SRI has no IVA rate with the code {rate_code!r}")
+    subtotal = cents(quantity * unit_price - discount)
+    return Line(
+        code=code,
+        description=description,
+        quantity=quantity,
+        unit_price=unit_price,
+        discount=discount,
+        subtotal=subtotal,
+        vat=cents(subtotal * rate / HUNDRED),
+        rate_code=rate_code,
+        rate_percentage=rate,
+    )