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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.2.3
+Version: 3.0.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -35,29 +35,32 @@ 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). |
+| `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
 
@@ -87,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}]
@@ -156,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")
 ```
@@ -256,13 +275,37 @@ 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
+
+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.
+
+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)
 
 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 +320,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 (reemplaza a tipo_frase/escenario)
+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,18 +374,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)` | FACT con complemento combustible (IVA + PETROLEO). |
+| `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": ...}`.
 
@@ -362,6 +426,7 @@ 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` |
 
 ## Manejo de errores
 

{digifact_sdk-2.2.3 → digifact_sdk-3.0.0}/README.md

@@ -11,29 +11,32 @@ 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). |
+| `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
 
@@ -63,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}]
@@ -132,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")
 ```
@@ -232,13 +251,37 @@ 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
+
+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.
+
+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)
 
 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 +296,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 (reemplaza a tipo_frase/escenario)
+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,18 +350,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)` | FACT con complemento combustible (IVA + PETROLEO). |
+| `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": ...}`.
 
@@ -338,6 +402,7 @@ 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` |
 
 ## Manejo de errores
 

{digifact_sdk-2.2.3 → digifact_sdk-3.0.0}/digifact_sdk/__init__.py

@@ -8,7 +8,7 @@ from .exceptions import (
     DigifactValidationError,
 )
 
-__version__ = "2.0.0"
+__version__ = "3.0.0"
 __all__ = [
     "DigifactClient",
     "DteResult",

{digifact_sdk-2.2.3 → digifact_sdk-3.0.0}/digifact_sdk/builder.py

@@ -27,6 +27,54 @@ def _adenda_code(doc_type: str) -> str:
     return ADENDA_CODE_ALT if doc_type in _ALT_ADENDA_TYPES else ADENDA_CODE_STD
 
 
+# ── Frases ───────────────────────────────────────────────────────────────────
+
+
+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 resolve_fuel_frases(
+    frases: list[dict] | None,
+    tipo_frase: str | None,
+    escenario: str | None,
+) -> 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})
+    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 +116,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 +145,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 +359,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 +383,7 @@ def build_fact(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -371,6 +426,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 +447,7 @@ def build_fcam(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -443,6 +500,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 +520,7 @@ def build_ndeb(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -527,6 +586,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 +606,7 @@ def build_ncre(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -609,6 +670,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 +684,7 @@ def build_nabn(
         afiliacion=afiliacion,
         tipo_frase="1",
         escenario="1",
+        frases=frases,
         email=seller_email,
     )
 
@@ -718,6 +781,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 +794,7 @@ def build_rdon(
         afiliacion=afiliacion,
         tipo_frase="4",
         escenario="4",
+        frases=frases,
         email=seller_email,
     )
 
@@ -769,6 +834,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 +851,7 @@ def build_fpeq(
         afiliacion="PEQ",
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -819,6 +886,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 +899,7 @@ def build_reci(
         afiliacion=afiliacion,
         tipo_frase="4",
         escenario="5",
+        frases=frases,
         email=seller_email,
     )
 
@@ -873,6 +942,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 +972,7 @@ def build_cca(
         afiliacion=afiliacion,
         tipo_frase=tf,
         escenario=es,
+        frases=frases,
         email=seller_email,
     )
 
@@ -1095,6 +1166,7 @@ def build_fact_combustible(
     afiliacion: str = "GEN",
     tipo_frase: str | None = None,
     escenario: str | None = None,
+    frases: list[dict] | None = None,
     seller_email: str | None = None,
 ) -> dict:
     """Build a FACT payload for combustible (fuel) invoices.
@@ -1104,6 +1176,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 +1187,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 +1201,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)
+
+    # 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,
         seller_name,
         seller_address,
         afiliacion=afiliacion,
-        tipo_frase=tf,
-        escenario=es,
+        frases=resolved_frases,
         email=seller_email,
     )
 
@@ -1135,12 +1218,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 +1233,5 @@ def build_fact_combustible(
             "GrandTotal": {"InvoiceTotal": grand_total},
         },
         "AdditionalDocumentInfo": _build_fuel_adenda(),
-    }
+    })
+    return combustible_payload