digifact-sdk 2.0.4__tar.gz → 2.2.0__tar.gz

{digifact_sdk-2.0.4 → digifact_sdk-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.0.4
+Version: 2.2.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -72,6 +72,21 @@ result = client.invoice(
     items=[{"description": "Producto", "qty": 2, "price": 50.00}]
 )
 
+# Full NIT buyer with explicit details (no auto-lookup)
+result = client.invoice(
+    buyer={
+        "taxid":    "12345678",
+        "name":     "EMPRESA EJEMPLO S.A.",
+        "address":  "6 AV 6-48 ZONA 9",
+        "city":     "01009",
+        "district": "GUATEMALA",
+        "state":    "GUATEMALA",
+        "country":  "GT",
+        "email":    "facturacion@empresa.com",  # optional
+    },
+    items=[{"description": "Producto", "qty": 1, "price": 100.00}]
+)
+
 # FCAM (Factura Cambiaria)
 result = client.invoice(
     buyer="12345678",
@@ -164,6 +179,62 @@ All money values are formatted as strings with 6 decimal places.
 }
 ```
 
+## Fuel invoices (FACT Combustible)
+
+Fuel invoices emit IVA **and** a PETROLEO pass-through tax per SAT spec.
+Items without `petroleo_amount` are treated as regular IVA-only items and
+can coexist in the same invoice.
+
+### Option A — rates set once at client init (recommended for gas stations)
+
+```python
+# Set PETROLEO rates once per fuel type (Q/gallon, from MEM or supplier invoice)
+client = DigifactClient(
+    taxid="12345678",
+    username="FELUSER",
+    password="secret",
+    petroleo_rates={"1": 4.70, "2": 4.60, "4": 1.30},  # SUPER / REGULAR / DIESEL
+)
+
+# Only petroleo_code is needed — petroleo_amount is filled in automatically
+result = client.fuel_invoice(
+    buyer="CF",
+    items=[
+        {"description": "GASOLINA SUPER",    "qty": 30, "price": 35.00, "petroleo_code": "1", "type": "Bien"},
+        {"description": "GASOLINA REGULAR",  "qty": 20, "price": 34.00, "petroleo_code": "2", "type": "Bien"},
+        {"description": "GASOLINA DIESEL",   "qty": 50, "price": 32.00, "petroleo_code": "4", "type": "Bien"},
+        # Regular items (no petroleo_code): IVA only, can coexist
+        {"description": "FILTRO DE ACEITE",    "qty": 1, "price": 45.00,  "type": "Bien"},
+        {"description": "SET DE CANDELAS NGK", "qty": 1, "price": 400.00, "type": "Bien"},
+    ],
+)
+print(result.auth_number)
+```
+
+### Option B — explicit per-item amount
+
+```python
+result = client.fuel_invoice(
+    buyer="CF",
+    items=[
+        {"description": "GASOLINA SUPER",   "qty": 1, "price": 35.00, "petroleo_amount": 4.70, "petroleo_code": "1", "type": "Bien"},
+        {"description": "GASOLINA DIESEL",  "qty": 1, "price": 32.00, "petroleo_amount": 1.30, "petroleo_code": "4", "type": "Bien"},
+    ],
+)
+```
+
+### Fuel item dict keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `description` | `str` | required | Line description |
+| `price` | `float\|Decimal` | required | Full consumer price per unit (PETROLEO + IVA-inclusive). This is what the customer pays at the pump. If the receipt shows a unit price *without* PETROLEO/IDP (e.g. `37.99`), add the per-unit IDP rate: `price = 37.99 + 4.70 = 42.69`. |
+| `qty` | `float\|Decimal` | `1` | Quantity |
+| `type` | `str` | `"Servicio"` | `"Bien"` or `"Servicio"` |
+| `unit_of_measure` | `str` | `"UNI"` | SAT unit code |
+| `petroleo_amount` | `float\|Decimal` | — | Per-unit PETROLEO tax; omit for IVA-only items |
+| `petroleo_code` | `str` | `"1"` | `"1"`=SUPER, `"2"`=REGULAR, `"4"`=DIESEL. Required when `petroleo_amount` is omitted and `petroleo_rates` is set; raises `DigifactValidationError` if the code is not found in the rates dict. |
+
 ## Running tests
 
 ```bash

{digifact_sdk-2.0.4 → digifact_sdk-2.2.0}/README.md

@@ -48,6 +48,21 @@ result = client.invoice(
     items=[{"description": "Producto", "qty": 2, "price": 50.00}]
 )
 
+# Full NIT buyer with explicit details (no auto-lookup)
+result = client.invoice(
+    buyer={
+        "taxid":    "12345678",
+        "name":     "EMPRESA EJEMPLO S.A.",
+        "address":  "6 AV 6-48 ZONA 9",
+        "city":     "01009",
+        "district": "GUATEMALA",
+        "state":    "GUATEMALA",
+        "country":  "GT",
+        "email":    "facturacion@empresa.com",  # optional
+    },
+    items=[{"description": "Producto", "qty": 1, "price": 100.00}]
+)
+
 # FCAM (Factura Cambiaria)
 result = client.invoice(
     buyer="12345678",
@@ -140,6 +155,62 @@ All money values are formatted as strings with 6 decimal places.
 }
 ```
 
+## Fuel invoices (FACT Combustible)
+
+Fuel invoices emit IVA **and** a PETROLEO pass-through tax per SAT spec.
+Items without `petroleo_amount` are treated as regular IVA-only items and
+can coexist in the same invoice.
+
+### Option A — rates set once at client init (recommended for gas stations)
+
+```python
+# Set PETROLEO rates once per fuel type (Q/gallon, from MEM or supplier invoice)
+client = DigifactClient(
+    taxid="12345678",
+    username="FELUSER",
+    password="secret",
+    petroleo_rates={"1": 4.70, "2": 4.60, "4": 1.30},  # SUPER / REGULAR / DIESEL
+)
+
+# Only petroleo_code is needed — petroleo_amount is filled in automatically
+result = client.fuel_invoice(
+    buyer="CF",
+    items=[
+        {"description": "GASOLINA SUPER",    "qty": 30, "price": 35.00, "petroleo_code": "1", "type": "Bien"},
+        {"description": "GASOLINA REGULAR",  "qty": 20, "price": 34.00, "petroleo_code": "2", "type": "Bien"},
+        {"description": "GASOLINA DIESEL",   "qty": 50, "price": 32.00, "petroleo_code": "4", "type": "Bien"},
+        # Regular items (no petroleo_code): IVA only, can coexist
+        {"description": "FILTRO DE ACEITE",    "qty": 1, "price": 45.00,  "type": "Bien"},
+        {"description": "SET DE CANDELAS NGK", "qty": 1, "price": 400.00, "type": "Bien"},
+    ],
+)
+print(result.auth_number)
+```
+
+### Option B — explicit per-item amount
+
+```python
+result = client.fuel_invoice(
+    buyer="CF",
+    items=[
+        {"description": "GASOLINA SUPER",   "qty": 1, "price": 35.00, "petroleo_amount": 4.70, "petroleo_code": "1", "type": "Bien"},
+        {"description": "GASOLINA DIESEL",  "qty": 1, "price": 32.00, "petroleo_amount": 1.30, "petroleo_code": "4", "type": "Bien"},
+    ],
+)
+```
+
+### Fuel item dict keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `description` | `str` | required | Line description |
+| `price` | `float\|Decimal` | required | Full consumer price per unit (PETROLEO + IVA-inclusive). This is what the customer pays at the pump. If the receipt shows a unit price *without* PETROLEO/IDP (e.g. `37.99`), add the per-unit IDP rate: `price = 37.99 + 4.70 = 42.69`. |
+| `qty` | `float\|Decimal` | `1` | Quantity |
+| `type` | `str` | `"Servicio"` | `"Bien"` or `"Servicio"` |
+| `unit_of_measure` | `str` | `"UNI"` | SAT unit code |
+| `petroleo_amount` | `float\|Decimal` | — | Per-unit PETROLEO tax; omit for IVA-only items |
+| `petroleo_code` | `str` | `"1"` | `"1"`=SUPER, `"2"`=REGULAR, `"4"`=DIESEL. Required when `petroleo_amount` is omitted and `petroleo_rates` is set; raises `DigifactValidationError` if the code is not found in the rates dict. |
+
 ## Running tests
 
 ```bash

{digifact_sdk-2.0.4 → digifact_sdk-2.2.0}/digifact_sdk/builder.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from decimal import Decimal
 from typing import Any
 
-from .tax import LineCalc, InvoiceTotals, fmt, gt_now
+from .tax import LineCalc, FuelLineCalc, InvoiceTotals, fmt, gt_now
 
 # ── No-IVA document types ─────────────────────────────────────────────────────
 NO_IVA_TYPES = {"FPEQ", "NABN", "RDON", "RECI"}
@@ -909,3 +909,175 @@ def build_cca(
         },
     }
     return payload
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Combustible (fuel) builder
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+def _build_fuel_items(
+    items: list[dict],
+) -> tuple[list[dict], str, str, str]:
+    """Build Items list for a combustible (fuel) invoice.
+
+    Items with 'petroleo_amount' are treated as fuel items and receive two
+    Tax entries (IVA + PETROLEO). Items without 'petroleo_amount' are treated
+    as regular IVA-only items. Both types may coexist in the same invoice.
+
+    Returns (line_items, grand_total_str, total_iva_str, total_petroleo_str).
+    """
+    line_items: list[dict] = []
+    grand_total    = Decimal("0")
+    total_iva      = Decimal("0")
+    total_petroleo = Decimal("0")
+
+    for i, item in enumerate(items, start=1):
+        qty   = Decimal(str(item.get("qty", 1)))
+        price = Decimal(str(item["price"]))
+        item_type = item.get("type", "Bien")
+        uom       = item.get("unit_of_measure", "UNI")
+        desc      = item["description"]
+
+        built: dict[str, Any] = {
+            "Number":        str(i),
+            "Codes":         None,
+            "Type":          item_type,
+            "Description":   desc,
+            "UnitOfMeasure": uom,
+            "Discounts":     None,
+        }
+
+        if "petroleo_amount" in item:
+            petrol_per_unit = Decimal(str(item["petroleo_amount"]))
+            petrol_code     = str(item.get("petroleo_code", "1"))
+
+            fc = FuelLineCalc(qty, price, petrol_per_unit)
+
+            built["Qty"]   = fc.f_qty()
+            built["Price"] = fc.f_price()
+            built["Taxes"] = {
+                "Tax": [
+                    {
+                        "Code":          "1",
+                        "Description":   "IVA",
+                        "TaxableAmount": fc.f_taxable(),
+                        "Amount":        fc.f_iva(),
+                    },
+                    {
+                        "Code":          petrol_code,
+                        "Description":   "PETROLEO",
+                        "TaxableAmount": fc.f_qty(),
+                        "Amount":        fc.f_petrol(),
+                    },
+                ]
+            }
+            built["Totals"] = {"TotalItem": fc.f_line_total()}
+
+            grand_total    += fc.line_total
+            total_iva      += fc.iva_amount
+            total_petroleo += fc.petrol_total
+        else:
+            lc = LineCalc(qty, price, taxable=True)
+
+            built["Qty"]   = lc.f_qty()
+            built["Price"] = lc.f_price()
+            built["Taxes"] = {
+                "Tax": [
+                    {
+                        "Code":          "1",
+                        "Description":   "IVA",
+                        "TaxableAmount": lc.f_taxable(),
+                        "Amount":        lc.f_iva(),
+                    }
+                ]
+            }
+            built["Totals"] = {"TotalItem": lc.f_line_total()}
+
+            grand_total += lc.line_total
+            total_iva   += lc.iva_amount
+
+        line_items.append(built)
+
+    return (
+        line_items,
+        fmt(grand_total),
+        fmt(total_iva),
+        fmt(total_petroleo),
+    )
+
+
+def _build_fuel_adenda() -> dict:
+    return {
+        "AdditionalInfo": [
+            {
+                "Code":  "00000013",
+                "Type":  "ADENDA",
+                "AditionalInfo": [
+                    {"Name": "VALIDAR_REFERENCIA_INTERNA", "Data": None, "Value": "NO_VALIDAR"},
+                ],
+            }
+        ]
+    }
+
+
+def build_fact_combustible(
+    taxid: str,
+    seller_name: str,
+    seller_address: str,
+    buyer: dict,
+    items: list[dict],
+    *,
+    afiliacion: str = "GEN",
+    tipo_frase: str = "1",
+    escenario: str = "1",
+    seller_email: str | None = None,
+) -> dict:
+    """Build a FACT payload for combustible (fuel) invoices.
+
+    Fuel items must include ``petroleo_amount`` (per-unit PETROLEO tax amount)
+    and optionally ``petroleo_code`` (SAT code: "1"=SUPER, "2"=REGULAR,
+    "4"=DIESEL; default "1"). Items without ``petroleo_amount`` are treated as
+    regular IVA-only items and may coexist in the same invoice.
+
+    Example fuel item::
+
+        {"description": "GASOLINA SUPER", "qty": 1, "price": 30.30,
+         "petroleo_amount": 4.70, "petroleo_code": "1", "type": "Bien"}
+
+    Example regular item in the same invoice::
+
+        {"description": "FILTRO DE ACEITE", "qty": 1, "price": 45.00, "type": "Bien"}
+    """
+    issue_dt, _, _ = gt_now()
+
+    line_items, grand_total, total_iva, total_petroleo = _build_fuel_items(items)
+
+    seller = _build_seller(
+        taxid,
+        seller_name,
+        seller_address,
+        afiliacion=afiliacion,
+        tipo_frase=tipo_frase,
+        escenario=escenario,
+        email=seller_email,
+    )
+
+    total_tax: list[dict] = [{"Description": "IVA", "Amount": total_iva}]
+    if float(total_petroleo) > 0.0:
+        total_tax.append({"Description": "PETROLEO", "Amount": total_petroleo})
+
+    return {
+        "Version": "1.00",
+        "CountryCode": "GT",
+        "Header": {"DocType": "FACT", "IssuedDateTime": issue_dt, "Currency": "GTQ"},
+        "Seller": seller,
+        "Buyer": buyer,
+        "ThirdParties": None,
+        "Items": line_items,
+        "Totals": {
+            "TotalTaxes": {"TotalTax": total_tax},
+            "GrandTotal": {"InvoiceTotal": grand_total},
+        },
+        "AdditionalDocumentInfo": _build_fuel_adenda(),
+    }

{digifact_sdk-2.0.4 → digifact_sdk-2.2.0}/digifact_sdk/client.py

@@ -11,6 +11,7 @@ import requests
 from .builder import (
     build_cca,
     build_fact,
+    build_fact_combustible,
     build_fcam,
     build_fesp,
     build_fpeq,
@@ -81,6 +82,12 @@ class DigifactClient:
         HTTP request timeout in seconds (default 120).
     session:
         Optional ``requests.Session`` to use (useful for testing / mocking).
+    petroleo_rates:
+        Optional mapping of PETROLEO code → per-unit tax amount, e.g.
+        ``{"1": 4.70, "2": 4.60, "4": 1.30}`` (SUPER/REGULAR/DIESEL).
+        When set, fuel items in :meth:`fuel_invoice` that provide
+        ``petroleo_code`` but omit ``petroleo_amount`` will have the amount
+        filled in automatically from this table.
     """
 
     def __init__(
@@ -97,6 +104,7 @@ class DigifactClient:
         tipo_personeria: str = "1",
         timeout: int = 120,
         session: requests.Session | None = None,
+        petroleo_rates: dict[str, float] | None = None,
     ) -> None:
         self.taxid = re.sub(r"\D", "", taxid)  # digits only
         if not self.taxid:
@@ -124,6 +132,7 @@ class DigifactClient:
         self._seller_name: str = seller_name
         self._seller_address: str = seller_address
         self._nit_cache: dict[str, dict] = {}
+        self.petroleo_rates: dict[str, float] = dict(petroleo_rates) if petroleo_rates else {}
 
         self._session = session or requests.Session()
 
@@ -404,6 +413,69 @@ class DigifactClient:
         data = self._certify(payload)
         return self._parse_result(data)
 
+    def fuel_invoice(
+        self,
+        buyer: str | dict,
+        items: list[dict],
+    ) -> DteResult:
+        """Emit a combustible (fuel) FACT invoice.
+
+        Parameters
+        ----------
+        buyer:
+            "CF", NIT string, CUI dict, or full buyer dict.
+        items:
+            List of item dicts. Fuel items must include:
+
+            * ``petroleo_amount`` – per-unit PETROLEO tax amount (float).
+            * ``petroleo_code`` – SAT code: ``"1"`` SUPER, ``"2"`` REGULAR,
+              ``"4"`` DIESEL (default ``"1"``).
+
+            Items without ``petroleo_amount`` are treated as regular IVA-only items.
+
+        Example::
+
+            client.fuel_invoice("CF", [
+                {"description": "GASOLINA SUPER", "qty": 1, "price": 30.30,
+                 "petroleo_amount": 4.70, "petroleo_code": "1", "type": "Bien"},
+                {"description": "FILTRO DE ACEITE", "qty": 1, "price": 45.00,
+                 "type": "Bien"},
+            ])
+        """
+        seller_name, seller_address = self._get_seller_info()
+        buyer_dict = self._resolve_buyer(buyer)
+        resolved = self._apply_petroleo_rates(items)
+        payload = build_fact_combustible(
+            self.taxid,
+            seller_name,
+            seller_address,
+            buyer_dict,
+            resolved,
+            afiliacion=self.afiliacion_iva,
+        )
+        data = self._certify(payload)
+        return self._parse_result(data)
+
+    def _apply_petroleo_rates(self, items: list[dict]) -> list[dict]:
+        """Fill in petroleo_amount from self.petroleo_rates when omitted.
+
+        Raises DigifactValidationError if an item has petroleo_code but no
+        petroleo_amount and no matching rate in petroleo_rates.
+        """
+        resolved = []
+        for item in items:
+            code = item.get("petroleo_code")
+            if code is not None and "petroleo_amount" not in item:
+                rate = self.petroleo_rates.get(str(code)) if self.petroleo_rates else None
+                if rate is None:
+                    raise DigifactValidationError(
+                        f"Item '{item.get('description', '')}' has petroleo_code='{code}' "
+                        "but no petroleo_amount and no matching rate in petroleo_rates."
+                    )
+                item = {**item, "petroleo_amount": rate}
+            resolved.append(item)
+        return resolved
+
     def credit_note(
         self,
         buyer: str | dict,

{digifact_sdk-2.0.4 → digifact_sdk-2.2.0}/digifact_sdk/tax.py

@@ -131,3 +131,49 @@ class InvoiceTotals:
 
     def f_total_iva(self) -> str:
         return fmt(self.total_iva)
+
+
+class FuelLineCalc:
+    """Holds all calculated values for a fuel (combustible) invoice line item.
+
+    The PETROLEO tax is a fixed pass-through amount supplied by the caller.
+    ``unit_price`` is the full consumer price per unit (PETROLEO + IVA-inclusive).
+    IVA is calculated on qty × (unit_price − petrol_amount_per_unit).
+    TotalItem = qty × unit_price.
+    """
+
+    def __init__(
+        self,
+        qty: Decimal,
+        unit_price: Decimal,
+        petrol_amount_per_unit: Decimal,
+    ) -> None:
+        self.qty = qty
+        self.unit_price = unit_price
+        net_per_unit = unit_price - petrol_amount_per_unit
+        self.gross = (qty * net_per_unit).quantize(Decimal("0.000001"), rounding=ROUND_HALF_UP)
+        self.petrol_total = (qty * petrol_amount_per_unit).quantize(
+            Decimal("0.000001"), rounding=ROUND_HALF_UP
+        )
+        self.line_total = (qty * unit_price).quantize(
+            Decimal("0.000001"), rounding=ROUND_HALF_UP
+        )
+        self.taxable_amount, self.iva_amount = calc_iva(self.gross)
+
+    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_petrol(self) -> str:
+        return fmt(self.petrol_total)

{digifact_sdk-2.0.4 → digifact_sdk-2.2.0}/digifact_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.0.4
+Version: 2.2.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -72,6 +72,21 @@ result = client.invoice(
     items=[{"description": "Producto", "qty": 2, "price": 50.00}]
 )
 
+# Full NIT buyer with explicit details (no auto-lookup)
+result = client.invoice(
+    buyer={
+        "taxid":    "12345678",
+        "name":     "EMPRESA EJEMPLO S.A.",
+        "address":  "6 AV 6-48 ZONA 9",
+        "city":     "01009",
+        "district": "GUATEMALA",
+        "state":    "GUATEMALA",
+        "country":  "GT",
+        "email":    "facturacion@empresa.com",  # optional
+    },
+    items=[{"description": "Producto", "qty": 1, "price": 100.00}]
+)
+
 # FCAM (Factura Cambiaria)
 result = client.invoice(
     buyer="12345678",
@@ -164,6 +179,62 @@ All money values are formatted as strings with 6 decimal places.
 }
 ```
 
+## Fuel invoices (FACT Combustible)
+
+Fuel invoices emit IVA **and** a PETROLEO pass-through tax per SAT spec.
+Items without `petroleo_amount` are treated as regular IVA-only items and
+can coexist in the same invoice.
+
+### Option A — rates set once at client init (recommended for gas stations)
+
+```python
+# Set PETROLEO rates once per fuel type (Q/gallon, from MEM or supplier invoice)
+client = DigifactClient(
+    taxid="12345678",
+    username="FELUSER",
+    password="secret",
+    petroleo_rates={"1": 4.70, "2": 4.60, "4": 1.30},  # SUPER / REGULAR / DIESEL
+)
+
+# Only petroleo_code is needed — petroleo_amount is filled in automatically
+result = client.fuel_invoice(
+    buyer="CF",
+    items=[
+        {"description": "GASOLINA SUPER",    "qty": 30, "price": 35.00, "petroleo_code": "1", "type": "Bien"},
+        {"description": "GASOLINA REGULAR",  "qty": 20, "price": 34.00, "petroleo_code": "2", "type": "Bien"},
+        {"description": "GASOLINA DIESEL",   "qty": 50, "price": 32.00, "petroleo_code": "4", "type": "Bien"},
+        # Regular items (no petroleo_code): IVA only, can coexist
+        {"description": "FILTRO DE ACEITE",    "qty": 1, "price": 45.00,  "type": "Bien"},
+        {"description": "SET DE CANDELAS NGK", "qty": 1, "price": 400.00, "type": "Bien"},
+    ],
+)
+print(result.auth_number)
+```
+
+### Option B — explicit per-item amount
+
+```python
+result = client.fuel_invoice(
+    buyer="CF",
+    items=[
+        {"description": "GASOLINA SUPER",   "qty": 1, "price": 35.00, "petroleo_amount": 4.70, "petroleo_code": "1", "type": "Bien"},
+        {"description": "GASOLINA DIESEL",  "qty": 1, "price": 32.00, "petroleo_amount": 1.30, "petroleo_code": "4", "type": "Bien"},
+    ],
+)
+```
+
+### Fuel item dict keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `description` | `str` | required | Line description |
+| `price` | `float\|Decimal` | required | Full consumer price per unit (PETROLEO + IVA-inclusive). This is what the customer pays at the pump. If the receipt shows a unit price *without* PETROLEO/IDP (e.g. `37.99`), add the per-unit IDP rate: `price = 37.99 + 4.70 = 42.69`. |
+| `qty` | `float\|Decimal` | `1` | Quantity |
+| `type` | `str` | `"Servicio"` | `"Bien"` or `"Servicio"` |
+| `unit_of_measure` | `str` | `"UNI"` | SAT unit code |
+| `petroleo_amount` | `float\|Decimal` | — | Per-unit PETROLEO tax; omit for IVA-only items |
+| `petroleo_code` | `str` | `"1"` | `"1"`=SUPER, `"2"`=REGULAR, `"4"`=DIESEL. Required when `petroleo_amount` is omitted and `petroleo_rates` is set; raises `DigifactValidationError` if the code is not found in the rates dict. |
+
 ## Running tests
 
 ```bash

{digifact_sdk-2.0.4 → digifact_sdk-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "digifact-sdk"
-version = "2.0.4"
+version = "2.2.0"
 description = "Python SDK for Digifact FEL Guatemala e-invoicing API"
 readme = "README.md"
 requires-python = ">=3.10"

{digifact_sdk-2.0.4 → digifact_sdk-2.2.0}/tests/test_integration.py

@@ -78,6 +78,74 @@ class TestTaxCalcUnit(unittest.TestCase):
         self.assertEqual(pad_taxid("GT.000012345678"), "000012345678")
 
 
+class TestFuelLineCalcUnit(unittest.TestCase):
+    def test_fuel_line_math(self):
+        from digifact_sdk.tax import FuelLineCalc
+        fc = FuelLineCalc(Decimal("1"), Decimal("35.00"), Decimal("4.70"))
+        self.assertEqual(fc.f_qty(),        "1.000000")
+        self.assertEqual(fc.f_price(),      "35.000000")
+        self.assertEqual(fc.f_line_total(), "35.000000")
+        self.assertEqual(fc.f_taxable(),    "27.053571")
+        self.assertEqual(fc.f_iva(),        "3.246429")
+        self.assertEqual(fc.f_petrol(),     "4.700000")
+
+    def test_taxable_plus_iva_equals_gross(self):
+        from digifact_sdk.tax import FuelLineCalc
+        fc = FuelLineCalc(Decimal("2"), Decimal("53.0"), Decimal("3.0"))
+        total = Decimal(fc.f_taxable()) + Decimal(fc.f_iva())
+        # taxable + iva must equal qty × net (= 100.00)
+        self.assertEqual(total, Decimal("100.000000"))
+        # lineTotal = qty × price = 2 × 53.00
+        self.assertEqual(fc.f_line_total(), "106.000000")
+
+
+class TestPetroleoRatesAutoFill(unittest.TestCase):
+    """Unit tests for DigifactClient._apply_petroleo_rates."""
+
+    def _make_client(self, rates=None):
+        from digifact_sdk.client import DigifactClient
+        return DigifactClient(
+            taxid="12345678",
+            username="U",
+            password="P",
+            petroleo_rates=rates,
+        )
+
+    def test_fills_amount_from_rates_when_code_set(self):
+        client = self._make_client({"1": 4.70, "4": 1.30})
+        resolved = client._apply_petroleo_rates([
+            {"description": "SUPER",  "price": 30.30, "petroleo_code": "1"},
+            {"description": "DIESEL", "price": 30.70, "petroleo_code": "4"},
+            {"description": "FILTRO", "price": 45.00},  # no code → untouched
+        ])
+        self.assertEqual(resolved[0]["petroleo_amount"], 4.70)
+        self.assertEqual(resolved[1]["petroleo_amount"], 1.30)
+        self.assertNotIn("petroleo_amount", resolved[2])
+
+    def test_explicit_amount_never_overwritten(self):
+        client = self._make_client({"1": 4.70})
+        resolved = client._apply_petroleo_rates([
+            {"description": "SUPER", "price": 30.30, "petroleo_code": "1", "petroleo_amount": 9.99},
+        ])
+        self.assertEqual(resolved[0]["petroleo_amount"], 9.99)
+
+    def test_missing_rate_raises_error(self):
+        from digifact_sdk.exceptions import DigifactValidationError
+        client = self._make_client()  # no rates
+        with self.assertRaises(DigifactValidationError):
+            client._apply_petroleo_rates([
+                {"description": "SUPER", "price": 30.30, "petroleo_code": "1"},
+            ])
+
+    def test_code_not_in_rates_raises_error(self):
+        from digifact_sdk.exceptions import DigifactValidationError
+        client = self._make_client({"1": 4.70})  # only SUPER configured
+        with self.assertRaises(DigifactValidationError):
+            client._apply_petroleo_rates([
+                {"description": "DIESEL", "price": 30.70, "petroleo_code": "4"},
+            ])
+
+
 class TestBuilderUnit(unittest.TestCase):
     def setUp(self):
         from digifact_sdk import builder
@@ -171,6 +239,54 @@ class TestBuilderUnit(unittest.TestCase):
         names = [d["Name"] for d in doc_info]
         self.assertIn("TipoPersoneria", names)
 
+    def test_buyer_nit_full_details(self):
+        from digifact_sdk.builder import _build_buyer_nit
+        buyer = _build_buyer_nit(
+            "12345678", "EMPRESA EJEMPLO S.A.",
+            address="6 AV 6-48 ZONA 9",
+            city="01009",
+            district="GUATEMALA",
+            state="GUATEMALA",
+            country="GT",
+            email="test@example.com",
+        )
+        self.assertEqual(buyer["TaxID"], "12345678")
+        self.assertEqual(buyer["Name"], "EMPRESA EJEMPLO S.A.")
+        self.assertEqual(buyer["AddressInfo"]["Address"], "6 AV 6-48 ZONA 9")
+        self.assertEqual(buyer["AddressInfo"]["City"], "01009")
+        self.assertEqual(buyer["Contact"]["EmailList"]["Email"][0], "test@example.com")
+
+    def test_build_fact_combustible_structure(self):
+        from digifact_sdk.builder import build_fact_combustible
+        buyer = {"TaxID": "CF", "Name": "CONSUMIDOR FINAL",
+                 "AddressInfo": {"Address": "CIUDAD", "City": "01010",
+                                 "District": "GUATEMALA", "State": "GUATEMALA", "Country": "GT"}}
+        payload = build_fact_combustible(
+            "12345678", "TEST", "CALLE",
+            buyer=buyer,
+            items=[
+                {"description": "SUPER",  "qty": 1, "price": 35.00,
+                 "petroleo_amount": 4.70, "petroleo_code": "1", "type": "Bien"},
+                {"description": "FILTRO", "qty": 1, "price": 45.00, "type": "Bien"},
+            ],
+        )
+        self.assertEqual(payload["Header"]["DocType"], "FACT")
+        # Fuel item: 2 taxes (IVA + PETROLEO)
+        fuel_taxes = payload["Items"][0]["Taxes"]["Tax"]
+        self.assertEqual(len(fuel_taxes), 2)
+        self.assertEqual(fuel_taxes[1]["Description"], "PETROLEO")
+        self.assertEqual(fuel_taxes[1]["Code"], "1")
+        # Regular item: 1 tax (IVA only)
+        reg_taxes = payload["Items"][1]["Taxes"]["Tax"]
+        self.assertEqual(len(reg_taxes), 1)
+        self.assertEqual(reg_taxes[0]["Description"], "IVA")
+        # Adenda code
+        adenda_code = payload["AdditionalDocumentInfo"]["AdditionalInfo"][0]["Code"]
+        self.assertEqual(adenda_code, "00000013")
+        # PETROLEO total appears in TotalTaxes
+        total_descs = [t["Description"] for t in payload["Totals"]["TotalTaxes"]["TotalTax"]]
+        self.assertIn("PETROLEO", total_descs)
+
 
 # ── Integration tests (shared client, 1 login total) ─────────────────────────
 
@@ -428,5 +544,22 @@ class TestGetDte(unittest.TestCase):
         self.assertIsInstance(info, dict)
 
 
+@unittest.skipIf(SKIP, SKIP_REASON)
+class TestFuelInvoice(unittest.TestCase):
+    def test_fuel_invoice_cf_mixed_items(self):
+        result = _client().fuel_invoice(
+            "CF",
+            [
+                {"description": "GASOLINA SUPER",   "qty": 1, "price": 35.00,
+                 "petroleo_amount": 4.70, "petroleo_code": "1", "type": "Bien"},
+                {"description": "GASOLINA REGULAR",  "qty": 1, "price": 34.00,
+                 "petroleo_amount": 4.60, "petroleo_code": "2", "type": "Bien"},
+                {"description": "FILTRO DE ACEITE",  "qty": 1, "price": 45.00, "type": "Bien"},
+            ],
+        )
+        self.assertTrue(result.auth_number, "Expected auth_number")
+        print(f"\n  FACT Combustible auth: {result.auth_number}")
+
+
 if __name__ == "__main__":
     unittest.main()