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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.2.3
+Version: 2.3.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -35,29 +35,33 @@ pip install digifact-sdk
 O desde el código fuente:
 
 ```bash
-pip install -e sdk/python/
+pip install -e python/
 ```
 
 ## Configuración del cliente (`DigifactClient(...)`)
 
+Ordenados de más usados a menos usados.
+
 | Parámetro | Tipo | Por defecto | Descripción |
 |-----------|------|-------------|-------------|
 | `taxid` | `str` | **requerido** | NIT del emisor. Acepta dígitos o con separadores (`"12345678"`, `"1234567-8"`); los no-dígitos se eliminan. Se rellena internamente a 12 caracteres. |
 | `username` | `str` | **requerido** | Usuario corto de Digifact (la parte después de `GT.<NIT>.`, p. ej. `"FELUSER"`). |
 | `password` | `str` | `""` | Contraseña de la cuenta. **Requerido** si no se provee `token`. |
-| `environment` | `str` | `"test"` | `"test"` o `"production"`. |
 | `token` | `str` | `""` | Bearer token preobtenido. Si se provee, se omite el login. |
-| `seller_name` | `str` | `""` | Nombre comercial del emisor. Si está vacío, se consulta en SAT vía `lookup_nit()`. |
+| `environment` | `str` | `"test"` | `"test"` o `"production"`. |
+| `seller_name` | `str` | `""` | Nombre del emisor. Para NIT individual es el nombre de la persona; para S.A. / S.E. es la razón social de la entidad. Si está vacío, se consulta en SAT vía `lookup_nit()`. |
 | `seller_address` | `str` | `""` | Dirección del emisor. Si está vacía, se consulta en SAT. |
-| `afiliacion_iva` | `str` | `"GEN"` | Afiliación IVA del RTU: `"GEN"`, `"PEQ"` o `"EXE"`. |
-| `tipo_personeria` | `str` | `"1"` | Código de `TipoPersoneria` del RTU (usado en RDON). |
 | `branch_code` | `str` | `"1"` | **Código del establecimiento** del RTU. Un NIT puede tener varios establecimientos (1, 2, 3…). Se escribe en `Seller.BranchInfo.Code`. |
-| `branch_name` | `str` | `"ESTABLECIMIENTO PRINCIPAL"` | Nombre comercial del establecimiento. Se escribe en `Seller.BranchInfo.Name`. |
-| `tipo_frase` | `str \| None` | `None` | Sobreescritura global de `TipoFrase`. Ver [frases](#configuración-de-frases-tipofrase--codigoescenario). |
-| `escenario` | `str \| None` | `None` | Sobreescritura global de `CodigoEscenario`. |
+| `branch_name` | `str` | `"ESTABLECIMIENTO PRINCIPAL"` | **Nombre comercial** de la sucursal — el mismo que aparece en la patente de comercio. Se escribe en `Seller.BranchInfo.Name`. |
+| `afiliacion_iva` | `str` | `"GEN"` | Afiliación IVA del RTU: `"GEN"`, `"PEQ"` o `"EXE"`. |
+| `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). |
-| `petroleo_rates` | `dict[str, float] \| None` | `None` | Mapa código PETROLEO → tarifa por unidad. Usado por `fuel_invoice()`. |
+| `tipo_personeria` | `str` | `"1"` | Código de `TipoPersoneria` del RTU. **Sólo aplica a RDON** (Recibo por Donación); ignóralo en los demás documentos. |
 
 ## Inicio rápido
 
@@ -256,13 +260,36 @@ 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
+
+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.
+
+```python
+# Sin cambios — el SDK agrega 9/18 y 9/19 automáticamente durante el subsidio
+result = client.fuel_invoice("CF", items)
+
+# Deshabilitarlo por llamada
+result = client.fuel_invoice("CF", items, auto_fuel_subsidy_frases=False)
+
+# Deshabilitarlo globalmente al construir el cliente
+client = DigifactClient(..., auto_fuel_subsidy_frases=False)
+
+# 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)
+
+# Frases completamente personalizadas (deshabilita auto-inyección)
+result = client.fuel_invoice("CF", items, frases=[{"tipo_frase": "1", "escenario": "1"}])
+```
+
+> **Nota:** `frases` y `tipo_frase`/`escenario` son **mutuamente exclusivos** — pasarlos juntos lanza `DigifactValidationError`.
+
 ## Configuración de frases (TipoFrase / CodigoEscenario)
 
 Todo DTE (excepto FESP) debe llevar un par `TipoFrase` + `CodigoEscenario`. El
 SDK elige valores por defecto adecuados, por lo que **no** hace falta
 configurar nada en el caso común.
 
-**Orden de precedencia:** argumentos por llamada → globales del constructor (`tipo_frase` / `escenario`) → tabla de valores por defecto.
+**Orden de precedencia:** argumentos por llamada → globales del constructor → tabla de valores por defecto.
 
 **Tabla de valores por defecto:**
 
@@ -277,10 +304,30 @@ configurar nada en el caso común.
 | FACT / FCAM / NCRE / NDEB | PEQ | `2` | `1` | |
 | FACT / FCAM / NCRE / NDEB | EXE | `4` | `1` | Exento |
 
-Tanto `tipo_frase` como `escenario` se pueden sobreescribir de forma
-independiente — por llamada (como argumentos con nombre) o globalmente al
-construir el cliente. Cuando se omiten, cada uno cae al global del
-constructor y luego a la tabla de valores por defecto.
+### Nueva API: `frases[]` (múltiples frases)
+
+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)
+client.fuel_invoice("CF", items, frases=[
+    {"tipo_frase": "1", "escenario": "1"},
+    {"tipo_frase": "9", "escenario": "18"},
+    {"tipo_frase": "9", "escenario": "19"},
+])
+
+# Globalmente en el constructor
+client = DigifactClient(
+    taxid="12345678", username="FELUSER", password="...",
+    frases=[{"tipo_frase": "1", "escenario": "2"}],  # ISR régimen opcional simplificado
+)
+```
+
+> **Regla:** `frases` y `tipo_frase`/`escenario` son **mutuamente exclusivos** en cada nivel (por llamada y en el constructor). Combinarlos lanza `DigifactValidationError`.
+
+### API legacy: `tipo_frase` / `escenario`
+
+Ambos parámetros siguen funcionando exactamente como antes para integraciones existentes.
 
 ```python
 # Sobreescritura por llamada (uno o ambos)
@@ -311,7 +358,7 @@ 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)` | FACT con complemento combustible (IVA + PETROLEO). |
+| `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. |
 | `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`. |
@@ -362,6 +409,8 @@ python -m pytest tests/ -v
 | `DIGIFACT_TAXID` | NIT del emisor (p. ej. `12345678`) |
 | `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.2.3 → digifact_sdk-2.3.0}/README.md

@@ -11,29 +11,33 @@ pip install digifact-sdk
 O desde el código fuente:
 
 ```bash
-pip install -e sdk/python/
+pip install -e python/
 ```
 
 ## Configuración del cliente (`DigifactClient(...)`)
 
+Ordenados de más usados a menos usados.
+
 | Parámetro | Tipo | Por defecto | Descripción |
 |-----------|------|-------------|-------------|
 | `taxid` | `str` | **requerido** | NIT del emisor. Acepta dígitos o con separadores (`"12345678"`, `"1234567-8"`); los no-dígitos se eliminan. Se rellena internamente a 12 caracteres. |
 | `username` | `str` | **requerido** | Usuario corto de Digifact (la parte después de `GT.<NIT>.`, p. ej. `"FELUSER"`). |
 | `password` | `str` | `""` | Contraseña de la cuenta. **Requerido** si no se provee `token`. |
-| `environment` | `str` | `"test"` | `"test"` o `"production"`. |
 | `token` | `str` | `""` | Bearer token preobtenido. Si se provee, se omite el login. |
-| `seller_name` | `str` | `""` | Nombre comercial del emisor. Si está vacío, se consulta en SAT vía `lookup_nit()`. |
+| `environment` | `str` | `"test"` | `"test"` o `"production"`. |
+| `seller_name` | `str` | `""` | Nombre del emisor. Para NIT individual es el nombre de la persona; para S.A. / S.E. es la razón social de la entidad. Si está vacío, se consulta en SAT vía `lookup_nit()`. |
 | `seller_address` | `str` | `""` | Dirección del emisor. Si está vacía, se consulta en SAT. |
-| `afiliacion_iva` | `str` | `"GEN"` | Afiliación IVA del RTU: `"GEN"`, `"PEQ"` o `"EXE"`. |
-| `tipo_personeria` | `str` | `"1"` | Código de `TipoPersoneria` del RTU (usado en RDON). |
 | `branch_code` | `str` | `"1"` | **Código del establecimiento** del RTU. Un NIT puede tener varios establecimientos (1, 2, 3…). Se escribe en `Seller.BranchInfo.Code`. |
-| `branch_name` | `str` | `"ESTABLECIMIENTO PRINCIPAL"` | Nombre comercial del establecimiento. Se escribe en `Seller.BranchInfo.Name`. |
-| `tipo_frase` | `str \| None` | `None` | Sobreescritura global de `TipoFrase`. Ver [frases](#configuración-de-frases-tipofrase--codigoescenario). |
-| `escenario` | `str \| None` | `None` | Sobreescritura global de `CodigoEscenario`. |
+| `branch_name` | `str` | `"ESTABLECIMIENTO PRINCIPAL"` | **Nombre comercial** de la sucursal — el mismo que aparece en la patente de comercio. Se escribe en `Seller.BranchInfo.Name`. |
+| `afiliacion_iva` | `str` | `"GEN"` | Afiliación IVA del RTU: `"GEN"`, `"PEQ"` o `"EXE"`. |
+| `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). |
-| `petroleo_rates` | `dict[str, float] \| None` | `None` | Mapa código PETROLEO → tarifa por unidad. Usado por `fuel_invoice()`. |
+| `tipo_personeria` | `str` | `"1"` | Código de `TipoPersoneria` del RTU. **Sólo aplica a RDON** (Recibo por Donación); ignóralo en los demás documentos. |
 
 ## Inicio rápido
 
@@ -232,13 +236,36 @@ 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
+
+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.
+
+```python
+# Sin cambios — el SDK agrega 9/18 y 9/19 automáticamente durante el subsidio
+result = client.fuel_invoice("CF", items)
+
+# Deshabilitarlo por llamada
+result = client.fuel_invoice("CF", items, auto_fuel_subsidy_frases=False)
+
+# Deshabilitarlo globalmente al construir el cliente
+client = DigifactClient(..., auto_fuel_subsidy_frases=False)
+
+# 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)
+
+# Frases completamente personalizadas (deshabilita auto-inyección)
+result = client.fuel_invoice("CF", items, frases=[{"tipo_frase": "1", "escenario": "1"}])
+```
+
+> **Nota:** `frases` y `tipo_frase`/`escenario` son **mutuamente exclusivos** — pasarlos juntos lanza `DigifactValidationError`.
+
 ## Configuración de frases (TipoFrase / CodigoEscenario)
 
 Todo DTE (excepto FESP) debe llevar un par `TipoFrase` + `CodigoEscenario`. El
 SDK elige valores por defecto adecuados, por lo que **no** hace falta
 configurar nada en el caso común.
 
-**Orden de precedencia:** argumentos por llamada → globales del constructor (`tipo_frase` / `escenario`) → tabla de valores por defecto.
+**Orden de precedencia:** argumentos por llamada → globales del constructor → tabla de valores por defecto.
 
 **Tabla de valores por defecto:**
 
@@ -253,10 +280,30 @@ configurar nada en el caso común.
 | FACT / FCAM / NCRE / NDEB | PEQ | `2` | `1` | |
 | FACT / FCAM / NCRE / NDEB | EXE | `4` | `1` | Exento |
 
-Tanto `tipo_frase` como `escenario` se pueden sobreescribir de forma
-independiente — por llamada (como argumentos con nombre) o globalmente al
-construir el cliente. Cuando se omiten, cada uno cae al global del
-constructor y luego a la tabla de valores por defecto.
+### Nueva API: `frases[]` (múltiples frases)
+
+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)
+client.fuel_invoice("CF", items, frases=[
+    {"tipo_frase": "1", "escenario": "1"},
+    {"tipo_frase": "9", "escenario": "18"},
+    {"tipo_frase": "9", "escenario": "19"},
+])
+
+# Globalmente en el constructor
+client = DigifactClient(
+    taxid="12345678", username="FELUSER", password="...",
+    frases=[{"tipo_frase": "1", "escenario": "2"}],  # ISR régimen opcional simplificado
+)
+```
+
+> **Regla:** `frases` y `tipo_frase`/`escenario` son **mutuamente exclusivos** en cada nivel (por llamada y en el constructor). Combinarlos lanza `DigifactValidationError`.
+
+### API legacy: `tipo_frase` / `escenario`
+
+Ambos parámetros siguen funcionando exactamente como antes para integraciones existentes.
 
 ```python
 # Sobreescritura por llamada (uno o ambos)
@@ -287,7 +334,7 @@ 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)` | FACT con complemento combustible (IVA + PETROLEO). |
+| `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. |
 | `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`. |
@@ -338,6 +385,8 @@ python -m pytest tests/ -v
 | `DIGIFACT_TAXID` | NIT del emisor (p. ej. `12345678`) |
 | `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.2.3 → digifact_sdk-2.3.0}/digifact_sdk/builder.py

@@ -7,6 +7,7 @@ Key intentional API typos preserved from the SAT/Digifact spec:
 """
 from __future__ import annotations
 
+import datetime as _datetime
 from decimal import Decimal
 from typing import Any
 
@@ -27,6 +28,69 @@ 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
+
+
+def _uniq_frases(frases: list[dict]) -> list[dict]:
+    seen: set[str] = set()
+    out: list[dict] = []
+    for f in frases:
+        key = f"{f['tipo_frase']}:{f['escenario']}"
+        if key not in seen:
+            seen.add(key)
+            out.append(f)
+    return out
+
+
+def _build_additionl_info_from_frases(frases: list[dict]) -> list[dict]:
+    """Build Seller.AdditionlInfo entries from a frases list.
+
+    Each frase gets a 1-based Data index so Digifact's NUC XSLT groups them into
+    separate <dte:Frase> elements. Confirmed via live API: Digifact counts the frases
+    correctly with this format (error becomes a NIT-authorization check, not XSLT failure).
+    """
+    out: list[dict] = []
+    for i, f in enumerate(frases, start=1):
+        out.append({"Name": "TipoFrase", "Data": str(i), "Value": str(f["tipo_frase"])})
+        out.append({"Name": "Escenario",  "Data": str(i), "Value": str(f["escenario"])})
+    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,
+) -> list[dict]:
+    """Return the final deduplicated frases list for a fuel invoice.
+
+    Called only after mutual-exclusivity validation (frases vs tipo_frase/escenario).
+    """
+    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"})
+    return _uniq_frases(result)
+
+
 def default_frase(doc_type: str, afiliacion: str = "GEN") -> tuple[str, str] | None:
     """Return default (TipoFrase, CodigoEscenario) for a (doc_type, afiliacion) combo.
 
@@ -68,6 +132,7 @@ def _build_seller(
     afiliacion: str = "GEN",
     tipo_frase: str | None = "1",
     escenario: str | None = "1",
+    frases: list[dict] | None = None,
     branch_code: str = "1",
     branch_name: str = "ESTABLECIMIENTO PRINCIPAL",
     city: str = "01010",
@@ -96,8 +161,12 @@ def _build_seller(
     }
     if email:
         seller["Contact"] = {"EmailList": {"Email": [email]}}
-    # AdditionlInfo — intentional typo in API spec
-    if tipo_frase is not None and escenario is not None:
+    # AdditionlInfo — intentional typo in API spec.
+    # Digifact's XSLT groups entries by 1-based Data index into separate <dte:Frase> elements.
+    if frases is not None:
+        if frases:
+            seller["AdditionlInfo"] = _build_additionl_info_from_frases(frases)
+    elif tipo_frase is not None and escenario is not None:
         seller["AdditionlInfo"] = [
             {"Name": "TipoFrase", "Data": "1", "Value": tipo_frase},
             {"Name": "Escenario", "Data": "1", "Value": escenario},
@@ -306,6 +375,7 @@ def build_fact(
     afiliacion: str = "GEN",
     tipo_frase: str | None = None,
     escenario: str | None = None,
+    frases: list[dict] | None = None,
     amount_str: str = "",
     observaciones: str = "-",
     extra_header: dict | None = None,
@@ -329,6 +399,7 @@ def build_fact(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -371,6 +442,7 @@ def build_fcam(
     seller_email: str | None = None,
     tipo_frase: str | None = None,
     escenario: str | None = None,
+    frases: list[dict] | None = None,
 ) -> dict:
     """Build a FCAM (Factura Cambiaria) DTE payload.
 
@@ -391,6 +463,7 @@ def build_fcam(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -443,6 +516,7 @@ def build_ndeb(
     seller_email: str | None = None,
     tipo_frase: str | None = None,
     escenario: str | None = None,
+    frases: list[dict] | None = None,
 ) -> dict:
     """Build a NDEB (Nota de Débito) DTE payload.
 
@@ -462,6 +536,7 @@ def build_ndeb(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -527,6 +602,7 @@ def build_ncre(
     seller_email: str | None = None,
     tipo_frase: str | None = None,
     escenario: str | None = None,
+    frases: list[dict] | None = None,
 ) -> dict:
     """Build a NCRE (Nota de Crédito) DTE payload.
 
@@ -546,6 +622,7 @@ def build_ncre(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -609,6 +686,7 @@ def build_nabn(
     amount_str: str = "",
     observaciones: str = "-",
     seller_email: str | None = None,
+    frases: list[dict] | None = None,
 ) -> dict:
     """Build a NABN (Nota de Abono) DTE payload — no IVA."""
     issue_dt, _, _ = gt_now()
@@ -622,6 +700,7 @@ def build_nabn(
         afiliacion=afiliacion,
         tipo_frase="1",
         escenario="1",
+        frases=frases,
         email=seller_email,
     )
 
@@ -718,6 +797,7 @@ def build_rdon(
     amount_str: str = "",
     observaciones: str = "-",
     seller_email: str | None = None,
+    frases: list[dict] | None = None,
 ) -> dict:
     """Build a RDON (Recibo por Donación) DTE payload — no IVA."""
     issue_dt, _, _ = gt_now()
@@ -730,6 +810,7 @@ def build_rdon(
         afiliacion=afiliacion,
         tipo_frase="4",
         escenario="4",
+        frases=frases,
         email=seller_email,
     )
 
@@ -769,6 +850,7 @@ def build_fpeq(
     seller_email: str | None = None,
     tipo_frase: str | None = None,
     escenario: str | None = None,
+    frases: list[dict] | None = None,
 ) -> dict:
     """Build a FPEQ (Factura Pequeño Contribuyente) DTE payload — no IVA, AfiliacionIVA=PEQ."""
     issue_dt, _, _ = gt_now()
@@ -785,6 +867,7 @@ def build_fpeq(
         afiliacion="PEQ",
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -819,6 +902,7 @@ def build_reci(
     student_id: str = "000000000",
     academic_unit: str = "01",
     seller_email: str | None = None,
+    frases: list[dict] | None = None,
 ) -> dict:
     """Build a RECI (Recibo) DTE payload — no IVA, universidad ADENDA."""
     issue_dt, _, _ = gt_now()
@@ -831,6 +915,7 @@ def build_reci(
         afiliacion=afiliacion,
         tipo_frase="4",
         escenario="5",
+        frases=frases,
         email=seller_email,
     )
 
@@ -873,6 +958,7 @@ def build_cca(
     seller_email: str | None = None,
     tipo_frase: str | None = None,
     escenario: str | None = None,
+    frases: list[dict] | None = None,
 ) -> dict:
     """Build a CCA (Cobro por Cuenta Ajena) FACT+CCA complemento payload.
 
@@ -902,6 +988,7 @@ def build_cca(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -1095,6 +1182,8 @@ def build_fact_combustible(
     afiliacion: str = "GEN",
     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.
@@ -1104,6 +1193,8 @@ 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.
 
+    ``frases`` and ``tipo_frase``/``escenario`` are mutually exclusive.
+
     Example fuel item::
 
         {"description": "GASOLINA SUPER", "qty": 1, "price": 30.30,
@@ -1113,6 +1204,12 @@ def build_fact_combustible(
 
         {"description": "FILTRO DE ACEITE", "qty": 1, "price": 45.00, "type": "Bien"}
     """
+    from .exceptions import DigifactValidationError
+    if frases is not None and (tipo_frase is not None or escenario is not None):
+        raise DigifactValidationError(
+            "frases and tipo_frase/escenario are mutually exclusive; use one or the other"
+        )
+
     issue_dt, _, _ = gt_now()
 
     line_items, grand_total, total_iva, total_petroleo = _build_fuel_items(items)
@@ -1121,13 +1218,16 @@ 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)
+
+    # All frases (base + any subsidy) 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,
         seller_name,
         seller_address,
         afiliacion=afiliacion,
-        tipo_frase=tf,
-        escenario=es,
+        frases=resolved_frases,
         email=seller_email,
     )
 
@@ -1135,12 +1235,14 @@ def build_fact_combustible(
     if float(total_petroleo) > 0.0:
         total_tax.append({"Description": "PETROLEO", "Amount": total_petroleo})
 
-    return {
+    combustible_payload: dict[str, Any] = {
         "Version": "1.00",
         "CountryCode": "GT",
         "Header": {"DocType": "FACT", "IssuedDateTime": issue_dt, "Currency": "GTQ"},
         "Seller": seller,
         "Buyer": buyer,
+    }
+    combustible_payload.update({
         "ThirdParties": None,
         "Items": line_items,
         "Totals": {
@@ -1148,4 +1250,5 @@ def build_fact_combustible(
             "GrandTotal": {"InvoiceTotal": grand_total},
         },
         "AdditionalDocumentInfo": _build_fuel_adenda(),
-    }
+    })
+    return combustible_payload

{digifact_sdk-2.2.3 → digifact_sdk-2.3.0}/digifact_sdk/client.py

@@ -127,6 +127,8 @@ class DigifactClient:
         tipo_personeria: str = "1",
         tipo_frase: str | None = None,
         escenario: str | None = None,
+        frases: list[dict] | None = None,
+        auto_fuel_subsidy_frases: bool | None = None,
         branch_code: str = "1",
         branch_name: str = "ESTABLECIMIENTO PRINCIPAL",
         timeout: int = 120,
@@ -140,6 +142,10 @@ class DigifactClient:
             raise ValueError("username is required")
         if not token and not password:
             raise ValueError("password or token is required")
+        if frases is not None and (tipo_frase is not None or escenario is not None):
+            raise ValueError(
+                "frases and tipo_frase/escenario are mutually exclusive; use one or the other"
+            )
 
         self.padded_taxid = pad_taxid(taxid)
         self.username = username
@@ -149,6 +155,8 @@ class DigifactClient:
         self.tipo_personeria = tipo_personeria
         self.tipo_frase = tipo_frase
         self.escenario = escenario
+        self.frases = frases
+        self.auto_fuel_subsidy_frases = auto_fuel_subsidy_frases
         self.branch_code = branch_code
         self.branch_name = branch_name
         self.timeout = timeout
@@ -369,7 +377,12 @@ class DigifactClient:
         """
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
-        tf, es = self._resolve_frase(doc_type, tipo_frase, escenario)
+        if self.frases is not None and tipo_frase is None and escenario is None:
+            eff_frases = self.frases
+            tf = es = None
+        else:
+            eff_frases = None
+            tf, es = self._resolve_frase(doc_type, tipo_frase, escenario)
 
         if doc_type == "FCAM":
             if not payment_terms:
@@ -386,6 +399,7 @@ class DigifactClient:
                 observaciones=observaciones,
                 tipo_frase=tf,
                 escenario=es,
+                frases=eff_frases,
             )
         elif doc_type == "FESP":
             payload = build_fesp(
@@ -406,6 +420,7 @@ class DigifactClient:
                 afiliacion=self.afiliacion_iva,
                 amount_str=amount_str,
                 observaciones=observaciones,
+                frases=eff_frases,
             )
         elif doc_type == "RDON":
             tp = tipo_personeria or self.tipo_personeria
@@ -419,6 +434,7 @@ class DigifactClient:
                 afiliacion=self.afiliacion_iva,
                 amount_str=amount_str,
                 observaciones=observaciones,
+                frases=eff_frases,
             )
         elif doc_type == "FPEQ":
             payload = build_fpeq(
@@ -431,6 +447,7 @@ class DigifactClient:
                 observaciones=observaciones,
                 tipo_frase=tf,
                 escenario=es,
+                frases=eff_frases,
             )
         elif doc_type == "RECI":
             payload = build_reci(
@@ -442,6 +459,7 @@ class DigifactClient:
                 afiliacion=self.afiliacion_iva,
                 amount_str=amount_str,
                 observaciones=observaciones,
+                frases=eff_frases,
             )
         else:
             # FACT (default), FACT CUI
@@ -455,6 +473,7 @@ class DigifactClient:
                 afiliacion=self.afiliacion_iva,
                 tipo_frase=tf,
                 escenario=es,
+                frases=eff_frases,
                 amount_str=amount_str,
                 observaciones=observaciones,
             )
@@ -474,7 +493,12 @@ class DigifactClient:
         """Emit a CCA (Cobro por Cuenta Ajena) FACT+CCA complemento."""
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
-        tf, es = self._resolve_frase("FACT", tipo_frase, escenario)
+        if self.frases is not None and tipo_frase is None and escenario is None:
+            eff_frases = self.frases
+            tf = es = None
+        else:
+            eff_frases = None
+            tf, es = self._resolve_frase("FACT", tipo_frase, escenario)
         payload = build_cca(
             self.taxid,
             seller_name,
@@ -485,6 +509,7 @@ class DigifactClient:
             afiliacion=self.afiliacion_iva,
             tipo_frase=tf,
             escenario=es,
+            frases=eff_frases,
         )
         data = self._certify(payload)
         return self._parse_result(data)
@@ -496,6 +521,8 @@ class DigifactClient:
         *,
         tipo_frase: str | None = None,
         escenario: str | None = None,
+        frases: list[dict] | None = None,
+        auto_fuel_subsidy_frases: bool | None = None,
     ) -> DteResult:
         """Emit a combustible (fuel) FACT invoice.
 
@@ -511,6 +538,15 @@ class DigifactClient:
               ``"4"`` DIESEL (default ``"1"``).
 
             Items without ``petroleo_amount`` are treated as regular IVA-only items.
+        frases:
+            Explicit list of ``{"tipo_frase": ..., "escenario": ...}`` dicts.
+            Mutually exclusive with ``tipo_frase``/``escenario``. When set,
+            auto-injection of subsidy frases (9/18, 9/19) is suppressed.
+        auto_fuel_subsidy_frases:
+            Override the client-level or default auto-injection behaviour.
+            ``None`` (default) falls back to the constructor setting, then
+            ``True``. Set to ``False`` (or ``DIGIFACT_DISABLE_AUTO_FUEL_SUBSIDY_FRASES=1``)
+            to disable auto-injection.
 
         Example::
 
@@ -521,10 +557,39 @@ class DigifactClient:
                  "type": "Bien"},
             ])
         """
+        import os
+        from .exceptions import DigifactValidationError
+
+        if frases is not None and (tipo_frase is not None or escenario is not None):
+            raise DigifactValidationError(
+                "frases and tipo_frase/escenario are mutually exclusive; use one or the other"
+            )
+
+        # Resolve effective frases: per-call → constructor → legacy tipo_frase/escenario
+        eff_frases: list[dict] | None
+        eff_tf: str | None
+        eff_es: str | None
+        if frases is not None:
+            eff_frases, eff_tf, eff_es = frases, None, None
+        elif self.frases is not None:
+            eff_frases, eff_tf, eff_es = self.frases, None, None
+        else:
+            eff_frases = None
+            eff_tf, eff_es = self._resolve_frase("FACT", tipo_frase, escenario)
+
+        # Resolve auto_enabled
+        if auto_fuel_subsidy_frases is not None:
+            auto_enabled = auto_fuel_subsidy_frases
+        elif self.auto_fuel_subsidy_frases is not None:
+            auto_enabled = self.auto_fuel_subsidy_frases
+        else:
+            auto_enabled = True
+        if os.environ.get("DIGIFACT_DISABLE_AUTO_FUEL_SUBSIDY_FRASES", "") == "1":
+            auto_enabled = False
+
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
         resolved = self._apply_petroleo_rates(items)
-        tf, es = self._resolve_frase("FACT", tipo_frase, escenario)
         payload = build_fact_combustible(
             self.taxid,
             seller_name,
@@ -532,8 +597,10 @@ class DigifactClient:
             buyer_dict,
             resolved,
             afiliacion=self.afiliacion_iva,
-            tipo_frase=tf,
-            escenario=es,
+            tipo_frase=eff_tf,
+            escenario=eff_es,
+            frases=eff_frases,
+            auto_fuel_subsidy_frases=auto_enabled,
         )
         data = self._certify(payload)
         return self._parse_result(data)
@@ -579,7 +646,12 @@ class DigifactClient:
         """
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
-        tf, es = self._resolve_frase("NCRE", tipo_frase, escenario)
+        if self.frases is not None and tipo_frase is None and escenario is None:
+            eff_frases = self.frases
+            tf = es = None
+        else:
+            eff_frases = None
+            tf, es = self._resolve_frase("NCRE", tipo_frase, escenario)
         payload = build_ncre(
             self.taxid,
             seller_name,
@@ -591,6 +663,7 @@ class DigifactClient:
             afiliacion=self.afiliacion_iva,
             tipo_frase=tf,
             escenario=es,
+            frases=eff_frases,
         )
         data = self._certify(payload)
         return self._parse_result(data)
@@ -616,7 +689,12 @@ class DigifactClient:
         """
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
-        tf, es = self._resolve_frase("NDEB", tipo_frase, escenario)
+        if self.frases is not None and tipo_frase is None and escenario is None:
+            eff_frases = self.frases
+            tf = es = None
+        else:
+            eff_frases = None
+            tf, es = self._resolve_frase("NDEB", tipo_frase, escenario)
         payload = build_ndeb(
             self.taxid,
             seller_name,
@@ -628,6 +706,7 @@ class DigifactClient:
             afiliacion=self.afiliacion_iva,
             tipo_frase=tf,
             escenario=es,
+            frases=eff_frases,
         )
         data = self._certify(payload)
         return self._parse_result(data)

{digifact_sdk-2.2.3 → digifact_sdk-2.3.0}/digifact_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.2.3
+Version: 2.3.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -35,29 +35,33 @@ pip install digifact-sdk
 O desde el código fuente:
 
 ```bash
-pip install -e sdk/python/
+pip install -e python/
 ```
 
 ## Configuración del cliente (`DigifactClient(...)`)
 
+Ordenados de más usados a menos usados.
+
 | Parámetro | Tipo | Por defecto | Descripción |
 |-----------|------|-------------|-------------|
 | `taxid` | `str` | **requerido** | NIT del emisor. Acepta dígitos o con separadores (`"12345678"`, `"1234567-8"`); los no-dígitos se eliminan. Se rellena internamente a 12 caracteres. |
 | `username` | `str` | **requerido** | Usuario corto de Digifact (la parte después de `GT.<NIT>.`, p. ej. `"FELUSER"`). |
 | `password` | `str` | `""` | Contraseña de la cuenta. **Requerido** si no se provee `token`. |
-| `environment` | `str` | `"test"` | `"test"` o `"production"`. |
 | `token` | `str` | `""` | Bearer token preobtenido. Si se provee, se omite el login. |
-| `seller_name` | `str` | `""` | Nombre comercial del emisor. Si está vacío, se consulta en SAT vía `lookup_nit()`. |
+| `environment` | `str` | `"test"` | `"test"` o `"production"`. |
+| `seller_name` | `str` | `""` | Nombre del emisor. Para NIT individual es el nombre de la persona; para S.A. / S.E. es la razón social de la entidad. Si está vacío, se consulta en SAT vía `lookup_nit()`. |
 | `seller_address` | `str` | `""` | Dirección del emisor. Si está vacía, se consulta en SAT. |
-| `afiliacion_iva` | `str` | `"GEN"` | Afiliación IVA del RTU: `"GEN"`, `"PEQ"` o `"EXE"`. |
-| `tipo_personeria` | `str` | `"1"` | Código de `TipoPersoneria` del RTU (usado en RDON). |
 | `branch_code` | `str` | `"1"` | **Código del establecimiento** del RTU. Un NIT puede tener varios establecimientos (1, 2, 3…). Se escribe en `Seller.BranchInfo.Code`. |
-| `branch_name` | `str` | `"ESTABLECIMIENTO PRINCIPAL"` | Nombre comercial del establecimiento. Se escribe en `Seller.BranchInfo.Name`. |
-| `tipo_frase` | `str \| None` | `None` | Sobreescritura global de `TipoFrase`. Ver [frases](#configuración-de-frases-tipofrase--codigoescenario). |
-| `escenario` | `str \| None` | `None` | Sobreescritura global de `CodigoEscenario`. |
+| `branch_name` | `str` | `"ESTABLECIMIENTO PRINCIPAL"` | **Nombre comercial** de la sucursal — el mismo que aparece en la patente de comercio. Se escribe en `Seller.BranchInfo.Name`. |
+| `afiliacion_iva` | `str` | `"GEN"` | Afiliación IVA del RTU: `"GEN"`, `"PEQ"` o `"EXE"`. |
+| `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). |
-| `petroleo_rates` | `dict[str, float] \| None` | `None` | Mapa código PETROLEO → tarifa por unidad. Usado por `fuel_invoice()`. |
+| `tipo_personeria` | `str` | `"1"` | Código de `TipoPersoneria` del RTU. **Sólo aplica a RDON** (Recibo por Donación); ignóralo en los demás documentos. |
 
 ## Inicio rápido
 
@@ -256,13 +260,36 @@ 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
+
+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.
+
+```python
+# Sin cambios — el SDK agrega 9/18 y 9/19 automáticamente durante el subsidio
+result = client.fuel_invoice("CF", items)
+
+# Deshabilitarlo por llamada
+result = client.fuel_invoice("CF", items, auto_fuel_subsidy_frases=False)
+
+# Deshabilitarlo globalmente al construir el cliente
+client = DigifactClient(..., auto_fuel_subsidy_frases=False)
+
+# 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)
+
+# Frases completamente personalizadas (deshabilita auto-inyección)
+result = client.fuel_invoice("CF", items, frases=[{"tipo_frase": "1", "escenario": "1"}])
+```
+
+> **Nota:** `frases` y `tipo_frase`/`escenario` son **mutuamente exclusivos** — pasarlos juntos lanza `DigifactValidationError`.
+
 ## Configuración de frases (TipoFrase / CodigoEscenario)
 
 Todo DTE (excepto FESP) debe llevar un par `TipoFrase` + `CodigoEscenario`. El
 SDK elige valores por defecto adecuados, por lo que **no** hace falta
 configurar nada en el caso común.
 
-**Orden de precedencia:** argumentos por llamada → globales del constructor (`tipo_frase` / `escenario`) → tabla de valores por defecto.
+**Orden de precedencia:** argumentos por llamada → globales del constructor → tabla de valores por defecto.
 
 **Tabla de valores por defecto:**
 
@@ -277,10 +304,30 @@ configurar nada en el caso común.
 | FACT / FCAM / NCRE / NDEB | PEQ | `2` | `1` | |
 | FACT / FCAM / NCRE / NDEB | EXE | `4` | `1` | Exento |
 
-Tanto `tipo_frase` como `escenario` se pueden sobreescribir de forma
-independiente — por llamada (como argumentos con nombre) o globalmente al
-construir el cliente. Cuando se omiten, cada uno cae al global del
-constructor y luego a la tabla de valores por defecto.
+### Nueva API: `frases[]` (múltiples frases)
+
+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)
+client.fuel_invoice("CF", items, frases=[
+    {"tipo_frase": "1", "escenario": "1"},
+    {"tipo_frase": "9", "escenario": "18"},
+    {"tipo_frase": "9", "escenario": "19"},
+])
+
+# Globalmente en el constructor
+client = DigifactClient(
+    taxid="12345678", username="FELUSER", password="...",
+    frases=[{"tipo_frase": "1", "escenario": "2"}],  # ISR régimen opcional simplificado
+)
+```
+
+> **Regla:** `frases` y `tipo_frase`/`escenario` son **mutuamente exclusivos** en cada nivel (por llamada y en el constructor). Combinarlos lanza `DigifactValidationError`.
+
+### API legacy: `tipo_frase` / `escenario`
+
+Ambos parámetros siguen funcionando exactamente como antes para integraciones existentes.
 
 ```python
 # Sobreescritura por llamada (uno o ambos)
@@ -311,7 +358,7 @@ 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)` | FACT con complemento combustible (IVA + PETROLEO). |
+| `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. |
 | `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`. |
@@ -362,6 +409,8 @@ python -m pytest tests/ -v
 | `DIGIFACT_TAXID` | NIT del emisor (p. ej. `12345678`) |
 | `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.2.3 → digifact_sdk-2.3.0}/pyproject.toml

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

{digifact_sdk-2.2.3 → digifact_sdk-2.3.0}/tests/test_integration.py

@@ -27,6 +27,7 @@ except ImportError:
 TAXID    = os.environ.get("DIGIFACT_TAXID", "")
 USERNAME = os.environ.get("DIGIFACT_USERNAME", "")
 PASSWORD = os.environ.get("DIGIFACT_PASSWORD", "")
+ENV      = os.environ.get("DIGIFACT_ENVIRONMENT", "test").lower()
 
 SKIP_REASON = "Set DIGIFACT_TAXID, DIGIFACT_USERNAME, DIGIFACT_PASSWORD to run integration tests"
 SKIP = not (TAXID and USERNAME and PASSWORD)
@@ -40,7 +41,7 @@ if not SKIP:
         taxid=TAXID,
         username=USERNAME,
         password=PASSWORD,
-        environment="test",
+        environment=ENV,
     )
 else:
     _CLIENT = None  # type: ignore[assignment]
@@ -288,6 +289,127 @@ class TestBuilderUnit(unittest.TestCase):
         self.assertIn("PETROLEO", total_descs)
 
 
+class TestFuelFrases(unittest.TestCase):
+    """Unit tests for frases[] / auto-fuel-subsidy-injection logic."""
+
+    def _buyer(self):
+        return {"TaxID": "CF", "Name": "CONSUMIDOR FINAL",
+                "AddressInfo": {"Address": "CIUDAD", "City": "01010",
+                                "District": "GUATEMALA", "State": "GUATEMALA", "Country": "GT"}}
+
+    def _items(self):
+        return [{"description": "SUPER", "qty": 1, "price": 35.00,
+                 "petroleo_amount": 4.70, "petroleo_code": "1", "type": "Bien"}]
+
+    def _additionl_frases(self, payload):
+        ai = payload["Seller"].get("AdditionlInfo", [])
+        frases = []
+        i = 0
+        while i + 1 < len(ai):
+            frases.append((ai[i]["Value"], ai[i + 1]["Value"]))
+            i += 2
+        return frases
+
+    def test_non_fuel_invoice_no_subsidy_frases(self):
+        from digifact_sdk.builder import build_fact
+        buyer = self._buyer()
+        payload = build_fact("12345678", "TEST", "CALLE", buyer=buyer,
+                             items=[{"description": "X", "qty": 1, "price": 100.0}])
+        frases = self._additionl_frases(payload)
+        self.assertEqual(len(frases), 1, "Regular invoice must have only the base frase")
+        self.assertNotIn(("9", "18"), frases)
+        self.assertNotIn(("9", "19"), frases)
+
+    def test_fuel_within_window_auto_inject(self):
+        from digifact_sdk.builder import build_fact_combustible, resolve_fuel_frases
+        # Use resolve_fuel_frases directly with a date known to be in window
+        result = resolve_fuel_frases(None, "1", "1", "2026-06-01T10:00:00", auto_enabled=True)
+        tf_es = [(f["tipo_frase"], f["escenario"]) for f in result]
+        self.assertIn(("1", "1"), tf_es, "Base frase must be present")
+        self.assertIn(("9", "18"), tf_es, "Escenario 18 must be auto-injected")
+        self.assertIn(("9", "19"), tf_es, "Escenario 19 must be auto-injected")
+        self.assertEqual(len(result), 3)
+
+    def test_fuel_custom_frases_no_auto_inject(self):
+        from digifact_sdk.builder import resolve_fuel_frases
+        custom = [{"tipo_frase": "2", "escenario": "1"}]
+        result = resolve_fuel_frases(custom, None, None, "2026-06-01T10:00:00", auto_enabled=True)
+        self.assertEqual(len(result), 1)
+        self.assertEqual(result[0]["tipo_frase"], "2")
+        self.assertNotIn(("9", "18"), [(f["tipo_frase"], f["escenario"]) for f in result])
+
+    def test_fuel_auto_disabled_no_inject(self):
+        from digifact_sdk.builder import resolve_fuel_frases
+        result = resolve_fuel_frases(None, "1", "1", "2026-06-01T10:00:00", auto_enabled=False)
+        tf_es = [(f["tipo_frase"], f["escenario"]) for f in result]
+        self.assertEqual(len(result), 1)
+        self.assertNotIn(("9", "18"), tf_es)
+        self.assertNotIn(("9", "19"), tf_es)
+
+    def test_deduplication(self):
+        from digifact_sdk.builder import resolve_fuel_frases
+        dupes = [{"tipo_frase": "9", "escenario": "18"},
+                 {"tipo_frase": "9", "escenario": "18"},
+                 {"tipo_frase": "9", "escenario": "19"}]
+        result = resolve_fuel_frases(dupes, None, None, "2026-06-01T10:00:00", auto_enabled=True)
+        self.assertEqual(len(result), 2)
+
+    def test_outside_window_no_inject(self):
+        from digifact_sdk.builder import resolve_fuel_frases
+        # Date before window
+        result_before = resolve_fuel_frases(None, "1", "1", "2026-04-26T10:00:00", auto_enabled=True)
+        self.assertEqual(len(result_before), 1)
+        # Date after window
+        result_after = resolve_fuel_frases(None, "1", "1", "2026-07-27T10:00:00", auto_enabled=True)
+        self.assertEqual(len(result_after), 1)
+
+    def test_build_fact_combustible_seller_has_additionl_info(self):
+        from digifact_sdk.builder import build_fact_combustible
+        payload = build_fact_combustible(
+            "12345678", "SELLER", "ADDR",
+            buyer=self._buyer(), items=self._items(),
+            auto_fuel_subsidy_frases=False,
+        )
+        ai = payload["Seller"].get("AdditionlInfo", [])
+        self.assertTrue(len(ai) >= 2, "Seller.AdditionlInfo must be present for fuel invoice")
+        self.assertEqual(ai[0]["Name"], "TipoFrase", "first AdditionlInfo entry must be TipoFrase")
+        self.assertEqual(ai[0]["Value"], "1")
+        self.assertEqual(ai[0]["Data"], "1")
+        self.assertEqual(ai[1]["Name"], "Escenario")
+        self.assertEqual(ai[1]["Data"], "1")
+
+    def test_build_fact_combustible_subsidy_frases_in_additionl_info(self):
+        from digifact_sdk.builder import build_fact_combustible
+        payload = build_fact_combustible(
+            "12345678", "SELLER", "ADDR",
+            buyer=self._buyer(), items=self._items(),
+            tipo_frase="1", escenario="1", auto_fuel_subsidy_frases=True,
+        )
+        ai = payload["Seller"].get("AdditionlInfo", [])
+        pairs = [(ai[i]["Value"], ai[i+1]["Value"]) for i in range(0, len(ai) - 1, 2)]
+        tipo_frases = [tf for tf, _ in pairs]
+        self.assertIn("1", tipo_frases, "TipoFrase=1 must be in AdditionlInfo")
+        # Within subsidy window: 9/18 and 9/19 must also be present
+        if len(pairs) > 1:
+            self.assertIn(("9", "18"), pairs, "9/18 must be in AdditionlInfo when within subsidy window")
+            self.assertIn(("9", "19"), pairs, "9/19 must be in AdditionlInfo when within subsidy window")
+            # Data must be the 1-based frase group index so the API creates separate <dte:Frase> elements
+            for idx, entry in enumerate(ai):
+                expected_data = str(idx // 2 + 1)
+                self.assertEqual(entry["Data"], expected_data, f"ai[{idx}]['Data'] must equal frase group index")
+
+    def test_mutual_exclusivity_raises(self):
+        from digifact_sdk.builder import build_fact_combustible
+        from digifact_sdk.exceptions import DigifactValidationError
+        with self.assertRaises(DigifactValidationError):
+            build_fact_combustible(
+                "12345678", "TEST", "CALLE",
+                buyer=self._buyer(), items=self._items(),
+                frases=[{"tipo_frase": "1", "escenario": "1"}],
+                tipo_frase="1",
+            )
+
+
 # ── Integration tests (shared client, 1 login total) ─────────────────────────
 
 @unittest.skipIf(SKIP, SKIP_REASON)
@@ -547,6 +669,10 @@ class TestGetDte(unittest.TestCase):
 @unittest.skipIf(SKIP, SKIP_REASON)
 class TestFuelInvoice(unittest.TestCase):
     def test_fuel_invoice_cf_mixed_items(self):
+        import base64, re as _re
+        is_production = ENV == "production"
+        # Test env does not support TipoFrase=9 (subsidio) — disable auto-injection there.
+        # On production, the default (True) applies and subsidio frases are included automatically.
         result = _client().fuel_invoice(
             "CF",
             [
@@ -556,10 +682,23 @@ class TestFuelInvoice(unittest.TestCase):
                  "petroleo_amount": 4.60, "petroleo_code": "2", "type": "Bien"},
                 {"description": "FILTRO DE ACEITE",  "qty": 1, "price": 45.00, "type": "Bien"},
             ],
+            auto_fuel_subsidy_frases=is_production,
         )
         self.assertTrue(result.auth_number, "Expected auth_number")
         print(f"\n  FACT Combustible auth: {result.auth_number}")
 
+        if is_production:
+            # Verify subsidio frases appear in the certified XML
+            dte   = _client().get_dte(result.auth_number, "XML")
+            b64   = (dte.get("RESPONSE") or [{}])[0].get("ResponseData1") or dte.get("responseData1", "")
+            self.assertTrue(b64, "ResponseData1 must be present")
+            xml   = base64.b64decode(b64).decode("utf-8", errors="replace")
+            frases = _re.findall(r'TipoFrase="\d+" CodigoEscenario="\d+"', xml)
+            print(f"  Frases en XML: {', '.join(frases)}")
+            self.assertIn('TipoFrase="9"',        xml, "TipoFrase=9 must appear in certified XML")
+            self.assertIn('CodigoEscenario="18"', xml, "CodigoEscenario=18 must appear in certified XML")
+            self.assertIn('CodigoEscenario="19"', xml, "CodigoEscenario=19 must appear in certified XML")
+
 
 if __name__ == "__main__":
     unittest.main()