digifact-sdk 2.3.0__tar.gz → 3.1.0__tar.gz

{digifact_sdk-2.3.0 → digifact_sdk-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.3.0
+Version: 3.1.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -57,7 +57,6 @@ Ordenados de más usados a menos usados.
 | `tipo_frase` | `str \| None` | `None` | Sobreescritura global de `TipoFrase` (legacy). **Mutuamente exclusivo con `frases`**. Ver [frases](#configuración-de-frases-tipofrase--codigoescenario). |
 | `escenario` | `str \| None` | `None` | Sobreescritura global de `CodigoEscenario` (legacy). **Mutuamente exclusivo con `frases`**. |
 | `frases` | `list[dict] \| None` | `None` | Lista de frases `{"tipo_frase": ..., "escenario": ...}`. Reemplaza a `tipo_frase`/`escenario`. **Mutuamente exclusivo** con ellos. Ver [frases](#configuración-de-frases-tipofrase--codigoescenario). |
-| `auto_fuel_subsidy_frases` | `bool \| None` | `None` | Controla la auto-inyección de frases 9/18 y 9/19 en facturas de combustible durante el periodo de subsidio. `None` = usar default (`True`). Ver [subsidio combustible](#subsidio-combustible-frases-automaticas). |
 | `petroleo_rates` | `dict[str, float] \| None` | `None` | Mapa código PETROLEO → tarifa por unidad. Usado sólo por `fuel_invoice()` (gasolineras). |
 | `timeout` | `int` | `120` | Timeout HTTP en segundos. |
 | `session` | `requests.Session \| None` | `None` | Sesión HTTP personalizada (útil para tests). |
@@ -91,7 +90,19 @@ result = client.invoice(
     ]
 )
 
-# FACT a receptor con CUI
+# FACT a receptor con CUI (DPI) — el nombre se consulta en SAT automáticamente
+result = client.invoice(
+    buyer={"taxid": "1234567890123", "type": "CUI"},
+    items=[{"description": "Producto", "qty": 2, "price": 50.00}]
+)
+
+# Equivalente: un string de 13 dígitos se resuelve como CUI
+result = client.invoice(
+    buyer="1234567890123",
+    items=[{"description": "Producto", "qty": 2, "price": 50.00}]
+)
+
+# Con nombre explícito no se consulta SAT
 result = client.invoice(
     buyer={"taxid": "3730617490101", "type": "CUI", "name": "Juan Pérez"},
     items=[{"description": "Producto", "qty": 2, "price": 50.00}]
@@ -160,6 +171,10 @@ result = client.credit_note_total(
 info = client.lookup_nit("12345678")
 print(info["name"])
 
+# Consulta de CUI (DPI) — SAT devuelve el nombre como "APELLIDOS, NOMBRES"
+info = client.lookup_cui("1234567890123")
+print(info["name"])   # "PEREZ LOPEZ, JUAN CARLOS"
+
 # Obtener DTE
 doc = client.get_dte("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
 ```
@@ -260,27 +275,54 @@ result = client.fuel_invoice(
 | `petroleo_amount` | `float\|Decimal` | — | Impuesto PETROLEO por unidad; omitir para ítems sólo-IVA |
 | `petroleo_code` | `str` | `"1"` | `"1"`=SUPER, `"2"`=REGULAR, `"4"`=DIESEL. Obligatorio cuando se omite `petroleo_amount` y `petroleo_rates` está configurado; lanza `DigifactValidationError` si el código no está en el diccionario de tarifas. |
 
-### Subsidio combustible — frases automáticas
+### Exención temporal (Decreto 22-2026)
 
-Durante el **periodo de subsidio de combustibles** (2026-04-27 (incl.) a 2026-07-27 (excl.)), SAT exige incluir frases especiales `TipoFrase=9, Escenario=18` y `TipoFrase=9, Escenario=19` en las facturas de combustible. **El SDK las agrega automáticamente** cuando la fecha de emisión cae dentro de la ventana — no se necesita cambiar ningún código existente.
+Del 1 de octubre al 31 de diciembre de 2026, y después hasta agotar el inventario comprado exento, la
+gasolina superior, la regular y el diésel se facturan sin IVA ni IDP. Se activa por ítem con el código de
+unidad gravable exento: `"18"` superior, `"21"` regular con etanol, `"20"` diésel y `"19"` regular sin
+etanol (sólo importadores). `price` es el precio de bomba, ya sin impuestos, y `qty` va en galones. El SDK
+envía ambos impuestos en cero y agrega las frases `9/23` y `4/38`; no hace falta `petroleo_amount` ni `petroleo_rates`.
 
 ```python
-# Sin cambios — el SDK agrega 9/18 y 9/19 automáticamente durante el subsidio
+from digifact_sdk import fuel_exemption
+
+items = [
+    {"description": "GASOLINA SUPER",   "qty": 10, "price": 30.00, "petroleo_code": "18", "unit_of_measure": "GAL"},
+    {"description": "GASOLINA REGULAR", "qty": 5,  "price": 28.00, "petroleo_code": "21", "unit_of_measure": "GAL"},
+    {"description": "DIESEL",           "qty": 20, "price": 27.00, "petroleo_code": "20", "unit_of_measure": "GAL"},
+]
 result = client.fuel_invoice("CF", items)
 
-# Deshabilitarlo por llamada
-result = client.fuel_invoice("CF", items, auto_fuel_subsidy_frases=False)
+# Montos y leyendas obligatorias para un ticket propio (el PDF de Digifact ya las imprime)
+exencion = fuel_exemption(items)
+print(exencion.idp, exencion.iva)   # 93.70 117.60
+print(exencion.leyendas)
+```
+
+Los detalles y las advertencias están en el [README principal](../README.md#exención-temporal-de-combustibles-decreto-22-2026).
 
-# Deshabilitarlo globalmente al construir el cliente
-client = DigifactClient(..., auto_fuel_subsidy_frases=False)
+### Subsidio combustible
 
-# Deshabilitarlo sin tocar código (útil si el presupuesto se agota antes de la fecha)
-# DIGIFACT_DISABLE_AUTO_FUEL_SUBSIDY_FRASES=1  (variable de entorno)
+El subsidio a la gasolina y al diésel **finalizó el jueves 2 de julio de 2026 a las 24:00**, antes de lo
+previsto: el presupuesto de Q2 mil millones (Decreto 11-2026, reglamentado por el Acuerdo Gubernativo
+64-2026) se agotó por la demanda. Por eso el SDK **nunca** envía las frases `TipoFrase=9, Escenario=18` ni
+`TipoFrase=9, Escenario=19` por su cuenta — no hay fecha de corte que valga para todos.
 
-# Frases completamente personalizadas (deshabilita auto-inyección)
-result = client.fuel_invoice("CF", items, frases=[{"tipo_frase": "1", "escenario": "1"}])
+Las estaciones con inventario adquirido bajo el subsidio deben mantener el precio rebajado hasta agotar ese
+producto, sujeto a verificación. Mientras te quede ese inventario, manda las frases explícitamente con
+`frases`; al agotarlo, deja de mandarlas:
+
+```python
+result = client.fuel_invoice("CF", items, frases=[
+    {"tipo_frase": "1", "escenario": "1"},   # frase base
+    {"tipo_frase": "9", "escenario": "18"},
+    {"tipo_frase": "9", "escenario": "19"},
+])
 ```
 
+> **Nota:** la leyenda del subsidio en la representación gráfica la genera Digifact a partir de las frases
+> del XML certificado, no este SDK. Al dejar de mandar las frases, deja de imprimirse sola.
+
 > **Nota:** `frases` y `tipo_frase`/`escenario` son **mutuamente exclusivos** — pasarlos juntos lanza `DigifactValidationError`.
 
 ## Configuración de frases (TipoFrase / CodigoEscenario)
@@ -299,7 +341,7 @@ configurar nada en el caso común.
 | FPEQ        | PEQ        | `2`       | `1`             | Pequeño contribuyente |
 | RDON        | cualquiera | `4`       | `4`             | Donaciones |
 | RECI        | cualquiera | `4`       | `5`             | Recibos (universidades) |
-| NABN        | cualquiera | `1`       | `1`             | Abonos |
+| NABN        | cualquiera | `9`       | `17`            | Abonos |
 | FACT / FCAM / NCRE / NDEB | **GEN** | `1` | `1` | Por defecto: ISR **régimen sobre utilidades trimestrales** |
 | FACT / FCAM / NCRE / NDEB | PEQ | `2` | `1` | |
 | FACT / FCAM / NCRE / NDEB | EXE | `4` | `1` | Exento |
@@ -309,7 +351,7 @@ configurar nada en el caso común.
 Usa `frases` cuando necesitas enviar **más de un par** TipoFrase/Escenario (p. ej. listados en resoluciones SAT). Es **mutuamente exclusivo** con `tipo_frase`/`escenario`.
 
 ```python
-# Lista explícita de frases (deshabilita tipo_frase/escenario y auto-inyección)
+# Lista explícita de frases (reemplaza a tipo_frase/escenario)
 client.fuel_invoice("CF", items, frases=[
     {"tipo_frase": "1", "escenario": "1"},
     {"tipo_frase": "9", "escenario": "18"},
@@ -358,18 +400,19 @@ Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `
 |--------|-------|-------------|
 | `invoice()` | `invoice(buyer, items, *, doc_type="FACT", payment_terms=None, amount_str="", observaciones="-", tipo_personeria=None, tipo_frase=None, escenario=None)` | Emite FACT, FCAM, FESP, FPEQ, NABN, RDON o RECI según `doc_type`. |
 | `cca_invoice()` | `cca_invoice(buyer, items, cobros, *, tipo_frase=None, escenario=None)` | FACT con complemento CCA. |
-| `fuel_invoice()` | `fuel_invoice(buyer, items, *, tipo_frase=None, escenario=None, frases=None, auto_fuel_subsidy_frases=None)` | FACT con complemento combustible (IVA + PETROLEO). Auto-inyecta frases 9/18 y 9/19 durante el subsidio. |
+| `fuel_invoice()` | `fuel_invoice(buyer, items, *, tipo_frase=None, escenario=None, frases=None)` | FACT con complemento combustible (IVA + PETROLEO). |
 | `credit_note()` | `credit_note(buyer, items, origin, reason, *, tipo_frase=None, escenario=None)` | Nota de crédito (NCRE). |
 | `debit_note()` | `debit_note(buyer, items, origin, reason, *, tipo_frase=None, escenario=None)` | Nota de débito (NDEB). |
 | `credit_note_total()` | `credit_note_total(auth_number, issue_datetime, reason="...", reference="")` | Nota de crédito total. Devuelve `dict`. |
 | `cancel()` | `cancel(auth_number, receiver_id, issue_datetime, reason="Anulación")` | Anula un DTE. Devuelve `dict`. |
 | `lookup_nit()` | `lookup_nit(nit)` | Consulta SAT. Devuelve `{"nit","name","address","city","district","state"}`. |
+| `lookup_cui()` | `lookup_cui(cui)` | Consulta SAT por CUI (DPI). Devuelve `{"cui","name","status"}`. El nombre viene como `"APELLIDOS, NOMBRES"`, tal como lo registra SAT. |
 | `get_dte()` | `get_dte(auth_number, fmt="JSON")` | Recupera el DTE (`"JSON"`, `"XML"`, `"HTML"`, `"PDF"`). |
 | `get_dte_info()` | `get_dte_info(auth_number)` | Metadatos del DTE. |
 
 ### Parámetros comunes
 
-- **`buyer`**: `"CF"` (consumidor final), un NIT string (`"12345678"` — se consulta el nombre), un dict CUI (`{"type":"CUI","taxid":...,"name":...}`) o un dict NIT explícito (`{"taxid","name","address","city","district","state","country","email"}`).
+- **`buyer`**: `"CF"` (consumidor final), un NIT string (`"12345678"` — se consulta el nombre), un CUI string de 13 dígitos (`"1234567890123"` — se consulta el nombre), un dict CUI (`{"type":"CUI","taxid":...}` — se consulta el nombre; con `"name"` explícito no se consulta) o un dict NIT explícito (`{"taxid","name","address","city","district","state","country","email"}`).
 - **`items`**: lista de dicts con `description` (str, req), `price` (float/Decimal, req), `qty` (1), `type` (`"Servicio"`/`"Bien"`), `unit_of_measure` (`"UNI"`), `discount` (opcional).
 - **`origin`** (NCRE/NDEB): `{"auth_number": ..., "date": "YYYY-MM-DD", "series": ..., "number": ...}`.
 
@@ -410,7 +453,6 @@ python -m pytest tests/ -v
 | `DIGIFACT_USERNAME` | Usuario (p. ej. `FELUSER`) |
 | `DIGIFACT_PASSWORD` | Contraseña de la cuenta |
 | `DIGIFACT_ENVIRONMENT` | `test` (default) o `production` |
-| `DIGIFACT_DISABLE_AUTO_FUEL_SUBSIDY_FRASES` | `1` para deshabilitar la auto-inyección de frases 9/18 y 9/19 sin tocar código |
 
 ## Manejo de errores
 

{digifact_sdk-2.3.0 → digifact_sdk-3.1.0}/README.md

@@ -33,7 +33,6 @@ Ordenados de más usados a menos usados.
 | `tipo_frase` | `str \| None` | `None` | Sobreescritura global de `TipoFrase` (legacy). **Mutuamente exclusivo con `frases`**. Ver [frases](#configuración-de-frases-tipofrase--codigoescenario). |
 | `escenario` | `str \| None` | `None` | Sobreescritura global de `CodigoEscenario` (legacy). **Mutuamente exclusivo con `frases`**. |
 | `frases` | `list[dict] \| None` | `None` | Lista de frases `{"tipo_frase": ..., "escenario": ...}`. Reemplaza a `tipo_frase`/`escenario`. **Mutuamente exclusivo** con ellos. Ver [frases](#configuración-de-frases-tipofrase--codigoescenario). |
-| `auto_fuel_subsidy_frases` | `bool \| None` | `None` | Controla la auto-inyección de frases 9/18 y 9/19 en facturas de combustible durante el periodo de subsidio. `None` = usar default (`True`). Ver [subsidio combustible](#subsidio-combustible-frases-automaticas). |
 | `petroleo_rates` | `dict[str, float] \| None` | `None` | Mapa código PETROLEO → tarifa por unidad. Usado sólo por `fuel_invoice()` (gasolineras). |
 | `timeout` | `int` | `120` | Timeout HTTP en segundos. |
 | `session` | `requests.Session \| None` | `None` | Sesión HTTP personalizada (útil para tests). |
@@ -67,7 +66,19 @@ result = client.invoice(
     ]
 )
 
-# FACT a receptor con CUI
+# FACT a receptor con CUI (DPI) — el nombre se consulta en SAT automáticamente
+result = client.invoice(
+    buyer={"taxid": "1234567890123", "type": "CUI"},
+    items=[{"description": "Producto", "qty": 2, "price": 50.00}]
+)
+
+# Equivalente: un string de 13 dígitos se resuelve como CUI
+result = client.invoice(
+    buyer="1234567890123",
+    items=[{"description": "Producto", "qty": 2, "price": 50.00}]
+)
+
+# Con nombre explícito no se consulta SAT
 result = client.invoice(
     buyer={"taxid": "3730617490101", "type": "CUI", "name": "Juan Pérez"},
     items=[{"description": "Producto", "qty": 2, "price": 50.00}]
@@ -136,6 +147,10 @@ result = client.credit_note_total(
 info = client.lookup_nit("12345678")
 print(info["name"])
 
+# Consulta de CUI (DPI) — SAT devuelve el nombre como "APELLIDOS, NOMBRES"
+info = client.lookup_cui("1234567890123")
+print(info["name"])   # "PEREZ LOPEZ, JUAN CARLOS"
+
 # Obtener DTE
 doc = client.get_dte("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
 ```
@@ -236,27 +251,54 @@ result = client.fuel_invoice(
 | `petroleo_amount` | `float\|Decimal` | — | Impuesto PETROLEO por unidad; omitir para ítems sólo-IVA |
 | `petroleo_code` | `str` | `"1"` | `"1"`=SUPER, `"2"`=REGULAR, `"4"`=DIESEL. Obligatorio cuando se omite `petroleo_amount` y `petroleo_rates` está configurado; lanza `DigifactValidationError` si el código no está en el diccionario de tarifas. |
 
-### Subsidio combustible — frases automáticas
+### Exención temporal (Decreto 22-2026)
 
-Durante el **periodo de subsidio de combustibles** (2026-04-27 (incl.) a 2026-07-27 (excl.)), SAT exige incluir frases especiales `TipoFrase=9, Escenario=18` y `TipoFrase=9, Escenario=19` en las facturas de combustible. **El SDK las agrega automáticamente** cuando la fecha de emisión cae dentro de la ventana — no se necesita cambiar ningún código existente.
+Del 1 de octubre al 31 de diciembre de 2026, y después hasta agotar el inventario comprado exento, la
+gasolina superior, la regular y el diésel se facturan sin IVA ni IDP. Se activa por ítem con el código de
+unidad gravable exento: `"18"` superior, `"21"` regular con etanol, `"20"` diésel y `"19"` regular sin
+etanol (sólo importadores). `price` es el precio de bomba, ya sin impuestos, y `qty` va en galones. El SDK
+envía ambos impuestos en cero y agrega las frases `9/23` y `4/38`; no hace falta `petroleo_amount` ni `petroleo_rates`.
 
 ```python
-# Sin cambios — el SDK agrega 9/18 y 9/19 automáticamente durante el subsidio
+from digifact_sdk import fuel_exemption
+
+items = [
+    {"description": "GASOLINA SUPER",   "qty": 10, "price": 30.00, "petroleo_code": "18", "unit_of_measure": "GAL"},
+    {"description": "GASOLINA REGULAR", "qty": 5,  "price": 28.00, "petroleo_code": "21", "unit_of_measure": "GAL"},
+    {"description": "DIESEL",           "qty": 20, "price": 27.00, "petroleo_code": "20", "unit_of_measure": "GAL"},
+]
 result = client.fuel_invoice("CF", items)
 
-# Deshabilitarlo por llamada
-result = client.fuel_invoice("CF", items, auto_fuel_subsidy_frases=False)
+# Montos y leyendas obligatorias para un ticket propio (el PDF de Digifact ya las imprime)
+exencion = fuel_exemption(items)
+print(exencion.idp, exencion.iva)   # 93.70 117.60
+print(exencion.leyendas)
+```
+
+Los detalles y las advertencias están en el [README principal](../README.md#exención-temporal-de-combustibles-decreto-22-2026).
 
-# Deshabilitarlo globalmente al construir el cliente
-client = DigifactClient(..., auto_fuel_subsidy_frases=False)
+### Subsidio combustible
 
-# Deshabilitarlo sin tocar código (útil si el presupuesto se agota antes de la fecha)
-# DIGIFACT_DISABLE_AUTO_FUEL_SUBSIDY_FRASES=1  (variable de entorno)
+El subsidio a la gasolina y al diésel **finalizó el jueves 2 de julio de 2026 a las 24:00**, antes de lo
+previsto: el presupuesto de Q2 mil millones (Decreto 11-2026, reglamentado por el Acuerdo Gubernativo
+64-2026) se agotó por la demanda. Por eso el SDK **nunca** envía las frases `TipoFrase=9, Escenario=18` ni
+`TipoFrase=9, Escenario=19` por su cuenta — no hay fecha de corte que valga para todos.
 
-# Frases completamente personalizadas (deshabilita auto-inyección)
-result = client.fuel_invoice("CF", items, frases=[{"tipo_frase": "1", "escenario": "1"}])
+Las estaciones con inventario adquirido bajo el subsidio deben mantener el precio rebajado hasta agotar ese
+producto, sujeto a verificación. Mientras te quede ese inventario, manda las frases explícitamente con
+`frases`; al agotarlo, deja de mandarlas:
+
+```python
+result = client.fuel_invoice("CF", items, frases=[
+    {"tipo_frase": "1", "escenario": "1"},   # frase base
+    {"tipo_frase": "9", "escenario": "18"},
+    {"tipo_frase": "9", "escenario": "19"},
+])
 ```
 
+> **Nota:** la leyenda del subsidio en la representación gráfica la genera Digifact a partir de las frases
+> del XML certificado, no este SDK. Al dejar de mandar las frases, deja de imprimirse sola.
+
 > **Nota:** `frases` y `tipo_frase`/`escenario` son **mutuamente exclusivos** — pasarlos juntos lanza `DigifactValidationError`.
 
 ## Configuración de frases (TipoFrase / CodigoEscenario)
@@ -275,7 +317,7 @@ configurar nada en el caso común.
 | FPEQ        | PEQ        | `2`       | `1`             | Pequeño contribuyente |
 | RDON        | cualquiera | `4`       | `4`             | Donaciones |
 | RECI        | cualquiera | `4`       | `5`             | Recibos (universidades) |
-| NABN        | cualquiera | `1`       | `1`             | Abonos |
+| NABN        | cualquiera | `9`       | `17`            | Abonos |
 | FACT / FCAM / NCRE / NDEB | **GEN** | `1` | `1` | Por defecto: ISR **régimen sobre utilidades trimestrales** |
 | FACT / FCAM / NCRE / NDEB | PEQ | `2` | `1` | |
 | FACT / FCAM / NCRE / NDEB | EXE | `4` | `1` | Exento |
@@ -285,7 +327,7 @@ configurar nada en el caso común.
 Usa `frases` cuando necesitas enviar **más de un par** TipoFrase/Escenario (p. ej. listados en resoluciones SAT). Es **mutuamente exclusivo** con `tipo_frase`/`escenario`.
 
 ```python
-# Lista explícita de frases (deshabilita tipo_frase/escenario y auto-inyección)
+# Lista explícita de frases (reemplaza a tipo_frase/escenario)
 client.fuel_invoice("CF", items, frases=[
     {"tipo_frase": "1", "escenario": "1"},
     {"tipo_frase": "9", "escenario": "18"},
@@ -334,18 +376,19 @@ Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `
 |--------|-------|-------------|
 | `invoice()` | `invoice(buyer, items, *, doc_type="FACT", payment_terms=None, amount_str="", observaciones="-", tipo_personeria=None, tipo_frase=None, escenario=None)` | Emite FACT, FCAM, FESP, FPEQ, NABN, RDON o RECI según `doc_type`. |
 | `cca_invoice()` | `cca_invoice(buyer, items, cobros, *, tipo_frase=None, escenario=None)` | FACT con complemento CCA. |
-| `fuel_invoice()` | `fuel_invoice(buyer, items, *, tipo_frase=None, escenario=None, frases=None, auto_fuel_subsidy_frases=None)` | FACT con complemento combustible (IVA + PETROLEO). Auto-inyecta frases 9/18 y 9/19 durante el subsidio. |
+| `fuel_invoice()` | `fuel_invoice(buyer, items, *, tipo_frase=None, escenario=None, frases=None)` | FACT con complemento combustible (IVA + PETROLEO). |
 | `credit_note()` | `credit_note(buyer, items, origin, reason, *, tipo_frase=None, escenario=None)` | Nota de crédito (NCRE). |
 | `debit_note()` | `debit_note(buyer, items, origin, reason, *, tipo_frase=None, escenario=None)` | Nota de débito (NDEB). |
 | `credit_note_total()` | `credit_note_total(auth_number, issue_datetime, reason="...", reference="")` | Nota de crédito total. Devuelve `dict`. |
 | `cancel()` | `cancel(auth_number, receiver_id, issue_datetime, reason="Anulación")` | Anula un DTE. Devuelve `dict`. |
 | `lookup_nit()` | `lookup_nit(nit)` | Consulta SAT. Devuelve `{"nit","name","address","city","district","state"}`. |
+| `lookup_cui()` | `lookup_cui(cui)` | Consulta SAT por CUI (DPI). Devuelve `{"cui","name","status"}`. El nombre viene como `"APELLIDOS, NOMBRES"`, tal como lo registra SAT. |
 | `get_dte()` | `get_dte(auth_number, fmt="JSON")` | Recupera el DTE (`"JSON"`, `"XML"`, `"HTML"`, `"PDF"`). |
 | `get_dte_info()` | `get_dte_info(auth_number)` | Metadatos del DTE. |
 
 ### Parámetros comunes
 
-- **`buyer`**: `"CF"` (consumidor final), un NIT string (`"12345678"` — se consulta el nombre), un dict CUI (`{"type":"CUI","taxid":...,"name":...}`) o un dict NIT explícito (`{"taxid","name","address","city","district","state","country","email"}`).
+- **`buyer`**: `"CF"` (consumidor final), un NIT string (`"12345678"` — se consulta el nombre), un CUI string de 13 dígitos (`"1234567890123"` — se consulta el nombre), un dict CUI (`{"type":"CUI","taxid":...}` — se consulta el nombre; con `"name"` explícito no se consulta) o un dict NIT explícito (`{"taxid","name","address","city","district","state","country","email"}`).
 - **`items`**: lista de dicts con `description` (str, req), `price` (float/Decimal, req), `qty` (1), `type` (`"Servicio"`/`"Bien"`), `unit_of_measure` (`"UNI"`), `discount` (opcional).
 - **`origin`** (NCRE/NDEB): `{"auth_number": ..., "date": "YYYY-MM-DD", "series": ..., "number": ...}`.
 
@@ -386,7 +429,6 @@ python -m pytest tests/ -v
 | `DIGIFACT_USERNAME` | Usuario (p. ej. `FELUSER`) |
 | `DIGIFACT_PASSWORD` | Contraseña de la cuenta |
 | `DIGIFACT_ENVIRONMENT` | `test` (default) o `production` |
-| `DIGIFACT_DISABLE_AUTO_FUEL_SUBSIDY_FRASES` | `1` para deshabilitar la auto-inyección de frases 9/18 y 9/19 sin tocar código |
 
 ## Manejo de errores
 

{digifact_sdk-2.3.0 → digifact_sdk-3.1.0}/digifact_sdk/__init__.py

@@ -1,4 +1,12 @@
 """Digifact FEL Guatemala SDK — Python package."""
+from .builder import (
+    FUEL_EXEMPT_DIESEL,
+    FUEL_EXEMPT_REGULAR_ETHANOL,
+    FUEL_EXEMPT_REGULAR_IMPORTER,
+    FUEL_EXEMPT_SUPER,
+    FuelExemption,
+    fuel_exemption,
+)
 from .client import DigifactClient, DteResult
 from .exceptions import (
     DigifactApiError,
@@ -8,7 +16,7 @@ from .exceptions import (
     DigifactValidationError,
 )
 
-__version__ = "2.0.0"
+__version__ = "3.1.0"
 __all__ = [
     "DigifactClient",
     "DteResult",
@@ -17,4 +25,10 @@ __all__ = [
     "DigifactApiError",
     "DigifactValidationError",
     "DigifactNitNotFoundError",
+    "FuelExemption",
+    "fuel_exemption",
+    "FUEL_EXEMPT_SUPER",
+    "FUEL_EXEMPT_REGULAR_IMPORTER",
+    "FUEL_EXEMPT_DIESEL",
+    "FUEL_EXEMPT_REGULAR_ETHANOL",
 ]

{digifact_sdk-2.3.0 → digifact_sdk-3.1.0}/digifact_sdk/builder.py

@@ -7,8 +7,8 @@ Key intentional API typos preserved from the SAT/Digifact spec:
 """
 from __future__ import annotations
 
-import datetime as _datetime
-from decimal import Decimal
+from dataclasses import dataclass
+from decimal import ROUND_HALF_UP, Decimal
 from typing import Any
 
 from .tax import LineCalc, FuelLineCalc, InvoiceTotals, fmt, gt_now
@@ -28,9 +28,68 @@ def _adenda_code(doc_type: str) -> str:
     return ADENDA_CODE_ALT if doc_type in _ALT_ADENDA_TYPES else ADENDA_CODE_STD
 
 
-# ── Fuel subsidy frases (Tipo 9, Escenarios 18 / 19) ─────────────────────────
-FUEL_SUBSIDY_START = _datetime.date(2026, 4, 27)
-FUEL_SUBSIDY_END   = _datetime.date(2026, 7, 27)  # exclusive
+# ── Exención temporal de combustibles (Decreto 22-2026) ──────────────────────
+FUEL_EXEMPT_SUPER = "18"
+FUEL_EXEMPT_REGULAR_IMPORTER = "19"
+FUEL_EXEMPT_DIESEL = "20"
+FUEL_EXEMPT_REGULAR_ETHANOL = "21"
+
+_FUEL_EXEMPT_IDP_RATES = {
+    FUEL_EXEMPT_SUPER: Decimal("4.70"),
+    FUEL_EXEMPT_REGULAR_IMPORTER: Decimal("4.60"),
+    FUEL_EXEMPT_DIESEL: Decimal("1.30"),
+    FUEL_EXEMPT_REGULAR_ETHANOL: Decimal("4.14"),
+}
+_FUEL_EXEMPTION_FRASES = [
+    {"tipo_frase": "9", "escenario": "23"},
+    {"tipo_frase": "4", "escenario": "38"},
+]
+_IVA_EXEMPT_CODE = "2"
+_IVA_RATE = Decimal("0.12")
+_CENTS = Decimal("0.01")
+
+
+def is_exempt_fuel_item(item: dict) -> bool:
+    return str(item.get("petroleo_code", "")) in _FUEL_EXEMPT_IDP_RATES
+
+
+@dataclass(frozen=True)
+class FuelExemption:
+    """Taxes a fuel sale would have paid without the Decreto 22-2026 exemption."""
+
+    iva: Decimal
+    idp: Decimal
+
+    @property
+    def leyendas(self) -> list[str]:
+        if not self.iva and not self.idp:
+            return []
+        return [
+            f"Monto de exención temporal de IDP aplicada: Q {fmt(self.idp, 2)}, según Decreto Número 22-2026",
+            f"Monto de exención temporal de IVA aplicada: Q {fmt(self.iva, 2)}, según Decreto Número 22-2026",
+        ]
+
+
+def fuel_exemption(items: list[dict]) -> FuelExemption:
+    """Return the exempted IVA and IDP for the exempt fuel items in ``items``.
+
+    ``qty`` must be in gallons: the IDP rates are per gallon.
+    """
+    exempt_total = Decimal("0")
+    idp = Decimal("0")
+    for item in items:
+        if not is_exempt_fuel_item(item):
+            continue
+        qty = Decimal(str(item.get("qty", 1)))
+        exempt_total += qty * Decimal(str(item["price"]))
+        idp += qty * _FUEL_EXEMPT_IDP_RATES[str(item["petroleo_code"])]
+    return FuelExemption(
+        iva=(exempt_total * _IVA_RATE).quantize(_CENTS, rounding=ROUND_HALF_UP),
+        idp=idp.quantize(_CENTS, rounding=ROUND_HALF_UP),
+    )
+
+
+# ── Frases ───────────────────────────────────────────────────────────────────
 
 
 def _uniq_frases(frases: list[dict]) -> list[dict]:
@@ -58,36 +117,29 @@ def _build_additionl_info_from_frases(frases: list[dict]) -> list[dict]:
     return out
 
 
-def _within_subsidy_window(issue_dt_iso: str) -> bool:
-    try:
-        d = _datetime.date.fromisoformat(issue_dt_iso[:10])
-        return FUEL_SUBSIDY_START <= d < FUEL_SUBSIDY_END
-    except (ValueError, TypeError):
-        return False
-
-
 def resolve_fuel_frases(
     frases: list[dict] | None,
     tipo_frase: str | None,
     escenario: str | None,
-    issue_dt_iso: str,
-    auto_enabled: bool = True,
+    *,
+    exempt: bool = False,
 ) -> list[dict]:
     """Return the final deduplicated frases list for a fuel invoice.
 
     Called only after mutual-exclusivity validation (frases vs tipo_frase/escenario).
+    ``exempt`` appends the Decreto 22-2026 frases, mandatory with exempt fuel codes.
     """
     if frases is not None:
         if not frases:
             from .exceptions import DigifactValidationError
             raise DigifactValidationError("frases must contain at least one TipoFrase/Escenario pair")
-        return _uniq_frases(frases)
-    result: list[dict] = []
-    if tipo_frase is not None and escenario is not None:
-        result.append({"tipo_frase": tipo_frase, "escenario": escenario})
-    if auto_enabled and _within_subsidy_window(issue_dt_iso):
-        result.append({"tipo_frase": "9", "escenario": "18"})
-        result.append({"tipo_frase": "9", "escenario": "19"})
+        result = list(frases)
+    else:
+        result = []
+        if tipo_frase is not None and escenario is not None:
+            result.append({"tipo_frase": tipo_frase, "escenario": escenario})
+    if exempt:
+        result.extend(_FUEL_EXEMPTION_FRASES)
     return _uniq_frases(result)
 
 
@@ -107,7 +159,7 @@ def default_frase(doc_type: str, afiliacion: str = "GEN") -> tuple[str, str] | N
     if doc_type == "RECI":
         return ("4", "5")
     if doc_type == "NABN":
-        return ("1", "1")
+        return ("9", "17")
     # FACT, NCRE, NDEB, FCAM, FACT+CCA, FACT+combustible
     if afi == "PEQ":
         return ("2", "1")
@@ -683,6 +735,8 @@ def build_nabn(
     items: list[dict],
     *,
     afiliacion: str = "GEN",
+    tipo_frase: str | None = "9",
+    escenario: str | None = "17",
     amount_str: str = "",
     observaciones: str = "-",
     seller_email: str | None = None,
@@ -692,14 +746,13 @@ def build_nabn(
     issue_dt, _, _ = gt_now()
     line_items, totals = _build_items(items, taxable=False)
 
-    # NABN: uses TipoFrase=1, Escenario=1 in seller (matches smoke runner)
     seller = _build_seller(
         taxid,
         seller_name,
         seller_address,
         afiliacion=afiliacion,
-        tipo_frase="1",
-        escenario="1",
+        tipo_frase=tipo_frase,
+        escenario=escenario,
         frases=frases,
         email=seller_email,
     )
@@ -1073,8 +1126,9 @@ def _build_fuel_items(
     """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.
+    Tax entries (IVA + PETROLEO). Items whose 'petroleo_code' is an exempt
+    code (18-21) carry both taxes at zero. Items without 'petroleo_amount' are
+    treated as regular IVA-only items. All types may coexist in the same invoice.
 
     Returns (line_items, grand_total_str, total_iva_str, total_petroleo_str).
     """
@@ -1099,7 +1153,31 @@ def _build_fuel_items(
             "Discounts":     None,
         }
 
-        if "petroleo_amount" in item:
+        if is_exempt_fuel_item(item):
+            lc = LineCalc(qty, price, taxable=False)
+
+            built["Qty"]   = lc.f_qty()
+            built["Price"] = lc.f_price()
+            built["Taxes"] = {
+                "Tax": [
+                    {
+                        "Code":          _IVA_EXEMPT_CODE,
+                        "Description":   "IVA",
+                        "TaxableAmount": lc.f_line_total(),
+                        "Amount":        lc.f_iva(),
+                    },
+                    {
+                        "Code":          str(item["petroleo_code"]),
+                        "Description":   "PETROLEO",
+                        "TaxableAmount": lc.f_qty(),
+                        "Amount":        fmt(0),
+                    },
+                ]
+            }
+            built["Totals"] = {"TotalItem": lc.f_line_total()}
+
+            grand_total += lc.line_total
+        elif "petroleo_amount" in item:
             petrol_per_unit = Decimal(str(item["petroleo_amount"]))
             petrol_code     = str(item.get("petroleo_code", "1"))
 
@@ -1183,7 +1261,6 @@ def build_fact_combustible(
     tipo_frase: str | None = None,
     escenario: str | None = None,
     frases: list[dict] | None = None,
-    auto_fuel_subsidy_frases: bool = True,
     seller_email: str | None = None,
 ) -> dict:
     """Build a FACT payload for combustible (fuel) invoices.
@@ -1193,6 +1270,11 @@ def build_fact_combustible(
     "4"=DIESEL; default "1"). Items without ``petroleo_amount`` are treated as
     regular IVA-only items and may coexist in the same invoice.
 
+    Fuel sold under the Decreto 22-2026 exemption uses the exempt codes instead
+    ("18"=SUPER, "21"=REGULAR with ethanol, "20"=DIESEL, "19"=REGULAR for
+    importers): ``price`` is the pump price without IVA or IDP, no
+    ``petroleo_amount`` is needed, and frases 9/23 and 4/38 are added.
+
     ``frases`` and ``tipo_frase``/``escenario`` are mutually exclusive.
 
     Example fuel item::
@@ -1218,9 +1300,10 @@ def build_fact_combustible(
     tf = tipo_frase if tipo_frase is not None else def_tf
     es = escenario if escenario is not None else def_es
 
-    resolved_frases = resolve_fuel_frases(frases, tf, es, issue_dt, auto_fuel_subsidy_frases)
+    has_exempt_fuel = any(is_exempt_fuel_item(item) for item in items)
+    resolved_frases = resolve_fuel_frases(frases, tf, es, exempt=has_exempt_fuel)
 
-    # All frases (base + any subsidy) go into Seller.AdditionlInfo as repeated pairs —
+    # All frases go into Seller.AdditionlInfo as repeated pairs —
     # that is the field the API reads to generate <dte:Frases> in the certified XML.
     seller = _build_seller(
         taxid,
@@ -1232,7 +1315,7 @@ def build_fact_combustible(
     )
 
     total_tax: list[dict] = [{"Description": "IVA", "Amount": total_iva}]
-    if float(total_petroleo) > 0.0:
+    if float(total_petroleo) > 0.0 or has_exempt_fuel:
         total_tax.append({"Description": "PETROLEO", "Amount": total_petroleo})
 
     combustible_payload: dict[str, Any] = {