digifact-sdk 2.0.1__py3-none-any.whl

digifact_sdk/exceptions.py

@@ -0,0 +1,76 @@
+"""Exceptions for the Digifact FEL SDK."""
+from __future__ import annotations
+
+
+class DigifactError(Exception):
+    """Base exception for all Digifact SDK errors."""
+
+    def __init__(self, message: str, code: int | None = None, raw: dict | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.raw = raw or {}
+
+    def __repr__(self) -> str:
+        return f"DigifactError(message={str(self)!r}, code={self.code!r})"
+
+
+class DigifactAuthError(DigifactError):
+    """Authentication / token error."""
+
+
+class DigifactApiError(DigifactError):
+    """API returned a non-success response."""
+
+
+class DigifactValidationError(DigifactError):
+    """Payload validation error (SAT or Digifact rejection)."""
+
+
+class DigifactNitNotFoundError(DigifactError):
+    """NIT lookup returned no result."""
+
+
+# ── SAT hint classifier ──────────────────────────────────────────────────────
+
+_HINTS: list[tuple[list[str], str]] = [
+    (
+        ["AfiliacionIVA", "MINIRTU", "RTU"],
+        "El NIT del emisor no tiene la afiliación de IVA indicada en su RTU (AfiliacionIVA). "
+        "Verifica que AfiliacionIVA sea GEN, PEQ o EXE según el RTU del emisor.",
+    ),
+    (
+        ["TipoPersoneria"],
+        "El valor de TipoPersoneria debe coincidir exactamente con el código registrado en el "
+        "RTU del emisor. Consulta el RTU en portal.sat.gob.gt.",
+    ),
+    (
+        ["SECCION 3.5", "9015", "ID Receptor"],
+        "NCRE/NDEB: el receptor del documento origen debe coincidir con el receptor del "
+        "documento de nota. Asegúrate de referenciar una factura cuyo comprador sea el mismo "
+        "que el de la nota.",
+    ),
+    (
+        ["NAMESPACE_UNKNOWN", "5035"],
+        "El complemento CCA requiere que el emisor tenga habilitado el namespace CCA en "
+        "Digifact. Contacta a soporte@digifact.com.gt.",
+    ),
+    (
+        ["FRASES"],
+        "Este tipo de DTE no permite las frases indicadas. Para FESP no incluyas "
+        "TipoFrase/Escenario en la sección Seller.",
+    ),
+    (
+        ["FechaEmision", "fecha"],
+        "Verifica el formato de fecha: debe ser 'YYYY-MM-DD HH:MM:SS' para cancelaciones y "
+        "ncredtotal, o 'YYYY-MM-DDTHH:MM:SS-06:00' para IssuedDateTime.",
+    ),
+]
+
+
+def classify_error(message: str) -> str | None:
+    """Return a developer hint for a known SAT/Digifact error pattern, or None."""
+    upper = message.upper()
+    for keywords, hint in _HINTS:
+        if any(kw.upper() in upper for kw in keywords):
+            return hint
+    return None

digifact_sdk/tax.py

@@ -0,0 +1,133 @@
+"""IVA calculations, money formatting, and Guatemala time helpers."""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone, timedelta
+from decimal import Decimal, ROUND_HALF_UP, getcontext
+
+# Use 28-digit precision to avoid rounding drift
+getcontext().prec = 28
+
+_GT_TZ = timezone(timedelta(hours=-6))
+_IVA_RATE = Decimal("12")
+_IVA_DIVISOR = Decimal("112")
+
+
+# ── Time helpers ─────────────────────────────────────────────────────────────
+
+def gt_now() -> tuple[str, str, str]:
+    """Return (iso_with_offset, space_datetime, date_only) in Guatemala time (UTC-6)."""
+    gt = datetime.now(_GT_TZ)
+    dt_offset = gt.strftime("%Y-%m-%dT%H:%M:%S-06:00")
+    dt_space = gt.strftime("%Y-%m-%d %H:%M:%S")
+    date_only = gt.strftime("%Y-%m-%d")
+    return dt_offset, dt_space, date_only
+
+
+def gt_now_dt() -> datetime:
+    """Return current datetime in Guatemala timezone."""
+    return datetime.now(_GT_TZ)
+
+
+# ── Tax ID helpers ────────────────────────────────────────────────────────────
+
+def pad_taxid(taxid: str) -> str:
+    """Strip non-digits and left-pad to 12 characters with zeros.
+
+    Example: '44653948' → '000044653948'
+    """
+    digits = re.sub(r"\D", "", taxid)
+    return digits.rjust(12, "0")
+
+
+# ── Money helpers ─────────────────────────────────────────────────────────────
+
+def fmt(value: Decimal | float | str, decimals: int = 6) -> str:
+    """Format a Decimal (or float/str) as a string with *decimals* decimal places."""
+    d = Decimal(str(value))
+    quantize_str = Decimal("1." + "0" * decimals)
+    return str(d.quantize(quantize_str, rounding=ROUND_HALF_UP))
+
+
+def calc_iva(line_total: "Decimal | float | str") -> tuple[Decimal, Decimal]:
+    """Return (taxable_amount, iva_amount) for an IVA-inclusive line_total.
+
+    taxable_amount = line_total / 1.12
+    iva_amount     = line_total - taxable_amount
+    """
+    line_total = Decimal(str(line_total))
+    taxable = (line_total * 100 / _IVA_DIVISOR).quantize(
+        Decimal("0.000001"), rounding=ROUND_HALF_UP
+    )
+    iva = (line_total - taxable).quantize(
+        Decimal("0.000001"), rounding=ROUND_HALF_UP
+    )
+    return taxable, iva
+
+
+class LineCalc:
+    """Holds all calculated values for a single invoice line item."""
+
+    def __init__(
+        self,
+        qty: Decimal,
+        unit_price: Decimal,
+        *,
+        taxable: bool = True,
+        discount: Decimal | None = None,
+    ) -> None:
+        self.qty = qty
+        self.unit_price = unit_price
+        self.gross = (qty * unit_price).quantize(Decimal("0.000001"), rounding=ROUND_HALF_UP)
+        self.discount = (discount or Decimal("0")).quantize(
+            Decimal("0.000001"), rounding=ROUND_HALF_UP
+        )
+        self.line_total = (self.gross - self.discount).quantize(
+            Decimal("0.000001"), rounding=ROUND_HALF_UP
+        )
+        if taxable:
+            self.taxable_amount, self.iva_amount = calc_iva(self.line_total)
+        else:
+            self.taxable_amount = Decimal("0")
+            self.iva_amount = Decimal("0")
+
+    # Convenience string formatters
+    def f_qty(self) -> str:
+        return fmt(self.qty)
+
+    def f_price(self) -> str:
+        return fmt(self.unit_price)
+
+    def f_line_total(self) -> str:
+        return fmt(self.line_total)
+
+    def f_taxable(self) -> str:
+        return fmt(self.taxable_amount)
+
+    def f_iva(self) -> str:
+        return fmt(self.iva_amount)
+
+    def f_discount(self) -> str:
+        return fmt(self.discount, decimals=2)
+
+
+class InvoiceTotals:
+    """Aggregate totals for a full invoice."""
+
+    def __init__(self, lines: list[LineCalc]) -> None:
+        self.lines = lines
+        self.grand_total = sum(ln.line_total for ln in lines).quantize(
+            Decimal("0.000001"), rounding=ROUND_HALF_UP
+        )
+        self.total_iva = sum(ln.iva_amount for ln in lines).quantize(
+            Decimal("0.000001"), rounding=ROUND_HALF_UP
+        )
+        self.total_taxable = sum(ln.taxable_amount for ln in lines).quantize(
+            Decimal("0.000001"), rounding=ROUND_HALF_UP
+        )
+
+    def f_grand_total(self) -> str:
+        return fmt(self.grand_total)
+
+    def f_total_iva(self) -> str:
+        return fmt(self.total_iva)

digifact_sdk-2.0.1.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: digifact-sdk
+Version: 2.0.1
+Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
+Author-email: AALONZOLU <noreply@github.com>
+License: MIT
+Keywords: digifact,fel,guatemala,factura,e-invoicing,sat
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: python-dotenv; extra == "dev"
+
+# Digifact FEL Guatemala — Python SDK
+
+Python SDK for the [Digifact](https://www.digifact.com.gt/) FEL (Factura Electrónica en Línea) Guatemala e-invoicing API.
+
+## Installation
+
+```bash
+pip install digifact-sdk
+```
+
+Or from source:
+
+```bash
+pip install -e sdk/python/
+```
+
+## Quick start
+
+```python
+from digifact_sdk import DigifactClient
+
+client = DigifactClient(
+    taxid="12345678",
+    username="FELUSER",
+    password="secret",
+    environment="test",  # or "production"
+)
+
+# FACT CF — consumer final, IVA calculated automatically
+result = client.invoice(
+    buyer="CF",
+    items=[{"description": "Consultoría", "qty": 1, "price": 100.00}]
+)
+print(result.auth_number)
+
+# FACT to NIT — buyer name fetched from SAT automatically
+result = client.invoice(
+    buyer="12345678",
+    items=[
+        {"description": "Laptop", "qty": 1, "price": 5000.00, "type": "Bien"},
+        {"description": "Soporte anual", "qty": 1, "price": 500.00},
+    ]
+)
+
+# FACT to CUI buyer
+result = client.invoice(
+    buyer={"taxid": "3730617490101", "type": "CUI", "name": "Juan Pérez"},
+    items=[{"description": "Producto", "qty": 2, "price": 50.00}]
+)
+
+# FCAM (Factura Cambiaria)
+result = client.invoice(
+    buyer="12345678",
+    items=[{"description": "Servicio", "qty": 1, "price": 500.00}],
+    doc_type="FCAM",
+    payment_terms=[{"date": "2026-04-18", "amount": 500.00}]
+)
+
+# Credit note (NCRE)
+result = client.credit_note(
+    buyer="12345678",
+    items=[{"description": "Devolución", "qty": 1, "price": 100.00}],
+    origin={
+        "auth_number": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
+        "date": "2026-03-18",
+        "series": "XXXXXXXX",
+        "number": "123456",
+    },
+    reason="Producto defectuoso"
+)
+
+# Debit note (NDEB)
+result = client.debit_note(
+    buyer="12345678",
+    items=[{"description": "Cargo adicional", "qty": 1, "price": 50.00}],
+    origin={...},
+    reason="Cargo por entrega express"
+)
+
+# Cancel a DTE
+result = client.cancel(
+    auth_number="XXXXXXXX-...",
+    receiver_id="CF",
+    issue_datetime="2026-03-18 21:40:14",
+    reason="Error en monto"
+)
+
+# Total credit note
+result = client.credit_note_total(
+    auth_number="XXXXXXXX-...",
+    issue_datetime="2026-03-18 21:40:14",
+    reason="Nota de crédito total"
+)
+
+# NIT lookup
+info = client.lookup_nit("12345678")
+print(info["name"])
+
+# Retrieve DTE
+doc = client.get_dte("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
+```
+
+## Document types
+
+| Type | Description | IVA |
+|------|-------------|-----|
+| `FACT` | Standard invoice | Yes |
+| `FCAM` | Factura Cambiaria (installments) | Yes |
+| `NDEB` | Debit note | Yes |
+| `NCRE` | Credit note | Yes |
+| `NABN` | Nota de Abono | No |
+| `FESP` | Factura Especial | Yes |
+| `RDON` | Recibo por Donación | No |
+| `FPEQ` | Factura Pequeño Contribuyente | No |
+| `RECI` | Recibo universitario | No |
+| `CCA` | Cobro por Cuenta Ajena | Yes |
+
+## IVA calculation
+
+Prices are IVA-inclusive (what the customer pays):
+
+```
+line_total     = qty × price
+taxable_amount = line_total / 1.12
+iva_amount     = line_total − taxable_amount
+```
+
+All money values are formatted as strings with 6 decimal places.
+
+## Item dict keys
+
+```python
+{
+    "description": str,          # required
+    "price": float | Decimal,    # required — unit price, IVA-inclusive
+    "qty": float | Decimal,      # optional, default 1
+    "type": str,                  # optional: "Servicio" (default) | "Bien"
+    "unit_of_measure": str,       # optional, default "UNI"
+    "discount": float | None,     # optional — line discount amount
+}
+```
+
+## Running tests
+
+```bash
+# Unit tests (no credentials needed)
+python -m pytest tests/ -v
+
+# Integration tests
+export DIGIFACT_TAXID=12345678
+export DIGIFACT_USERNAME=FELUSER
+export DIGIFACT_PASSWORD=your_password
+python -m pytest tests/ -v
+```
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `DIGIFACT_TAXID` | Fiscal ID (e.g. `12345678`) |
+| `DIGIFACT_USERNAME` | Username (e.g. `FELUSER`) |
+| `DIGIFACT_PASSWORD` | Account password |
+
+## Error handling
+
+```python
+from digifact_sdk import (
+    DigifactError,          # base
+    DigifactAuthError,      # auth failure
+    DigifactApiError,       # HTTP / API error
+    DigifactValidationError, # SAT rejection
+    DigifactNitNotFoundError, # NIT not found
+)
+
+try:
+    result = client.invoice("CF", [...])
+except DigifactValidationError as exc:
+    print(f"SAT rejected: {exc}")
+    print(f"Code: {exc.code}")
+    print(f"Raw: {exc.raw}")
+except DigifactError as exc:
+    print(f"SDK error: {exc}")
+```

digifact_sdk-2.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+digifact_sdk/__init__.py,sha256=P_rGntB3SvBSk5lrwARtjajCig0cbZeccLQVDoy_n5s,459
+digifact_sdk/builder.py,sha256=z8ALSyniR0fHN_bAsPCv_VvnS424GfOYU9pK3lnDbgo,27980
+digifact_sdk/client.py,sha256=a5q9m0_QZNjU2b8yzk312xVS3lopE3o9eBFUAyM5BN8,24560
+digifact_sdk/exceptions.py,sha256=5TYB70O13McAlA1GjpcpQZ36SZVO8AQytdvJkg-WRzY,2659
+digifact_sdk/tax.py,sha256=fYw-5tt-Iblt5g6rfGhTrterBuCzek7jGHtTQyGoiNE,4581
+digifact_sdk-2.0.1.dist-info/METADATA,sha256=5JzDDco0cHBEmHdeTL1wjZPmGHptWEe5Gm9RHe7U-lY,5473
+digifact_sdk-2.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+digifact_sdk-2.0.1.dist-info/top_level.txt,sha256=AkYqgzigsWPcxc8Rft51PtPMcr4NEi6daW2fXNpsBZE,13
+digifact_sdk-2.0.1.dist-info/RECORD,,

digifact_sdk-2.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

digifact_sdk-2.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+digifact_sdk