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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.2.2
+Version: 2.3.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -35,9 +35,34 @@ 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`. |
+| `token` | `str` | `""` | Bearer token preobtenido. Si se provee, se omite el login. |
+| `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. |
+| `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** 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). |
+| `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
 
 ```python
@@ -235,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:**
 
@@ -256,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)
@@ -282,6 +350,45 @@ client = DigifactClient(
 Para descubrir el par correcto en un caso particular, revisa las afiliaciones
 del RTU en el portal de SAT.
 
+## Referencia de métodos
+
+Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `series`, `number`, `issue_datetime`, `raw`.
+
+| Método | Firma | Descripción |
+|--------|-------|-------------|
+| `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. |
+| `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"}`. |
+| `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"}`).
+- **`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": ...}`.
+
+## Establecimiento (sucursal)
+
+Cada NIT puede tener varios establecimientos registrados en el RTU. Configúralos al crear el cliente:
+
+```python
+client = DigifactClient(
+    taxid="12345678",
+    username="FELUSER",
+    password="secret",
+    branch_code="2",
+    branch_name="SUCURSAL ZONA 10",
+)
+```
+
+Aplican a todos los DTE emitidos por ese cliente. Si se omiten, se usan los defaults `"1"` / `"ESTABLECIMIENTO PRINCIPAL"`.
+
 ## Ejecutar las pruebas
 
 ```bash
@@ -302,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.2 → digifact_sdk-2.3.0}/README.md

@@ -11,9 +11,34 @@ 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`. |
+| `token` | `str` | `""` | Bearer token preobtenido. Si se provee, se omite el login. |
+| `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. |
+| `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** 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). |
+| `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
 
 ```python
@@ -211,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:**
 
@@ -232,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)
@@ -258,6 +326,45 @@ client = DigifactClient(
 Para descubrir el par correcto en un caso particular, revisa las afiliaciones
 del RTU en el portal de SAT.
 
+## Referencia de métodos
+
+Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `series`, `number`, `issue_datetime`, `raw`.
+
+| Método | Firma | Descripción |
+|--------|-------|-------------|
+| `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. |
+| `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"}`. |
+| `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"}`).
+- **`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": ...}`.
+
+## Establecimiento (sucursal)
+
+Cada NIT puede tener varios establecimientos registrados en el RTU. Configúralos al crear el cliente:
+
+```python
+client = DigifactClient(
+    taxid="12345678",
+    username="FELUSER",
+    password="secret",
+    branch_code="2",
+    branch_name="SUCURSAL ZONA 10",
+)
+```
+
+Aplican a todos los DTE emitidos por ese cliente. Si se omiten, se usan los defaults `"1"` / `"ESTABLECIMIENTO PRINCIPAL"`.
+
 ## Ejecutar las pruebas
 
 ```bash
@@ -278,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.2 → 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