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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.2.2
+Version: 2.2.3
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -38,6 +38,27 @@ O desde el código fuente:
 pip install -e sdk/python/
 ```
 
+## Configuración del cliente (`DigifactClient(...)`)
+
+| 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()`. |
+| `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`. |
+| `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()`. |
+
 ## Inicio rápido
 
 ```python
@@ -282,6 +303,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)` | 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"}`. |
+| `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

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

@@ -14,6 +14,27 @@ O desde el código fuente:
 pip install -e sdk/python/
 ```
 
+## Configuración del cliente (`DigifactClient(...)`)
+
+| 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()`. |
+| `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`. |
+| `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()`. |
+
 ## Inicio rápido
 
 ```python
@@ -258,6 +279,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)` | 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"}`. |
+| `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

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

@@ -61,30 +61,52 @@ class DigifactClient:
 
     Parameters
     ----------
-    taxid:
-        Fiscal ID of the issuer (digits only; will be padded to 12 chars).
-    username:
-        Short username, e.g. "FELUSER".
-    password:
-        Account password. Either password or token must be provided.
-    environment:
-        "test" (default) or "production".
-    token:
-        Pre-obtained bearer token. If provided, login is skipped.
-    seller_name:
-        Override the seller name (default: fetched from SAT NIT lookup).
-    seller_address:
-        Override the seller address.
-    afiliacion_iva:
-        IVA affiliation code ("GEN", "PEQ", "EXE"). Default "GEN".
-    tipo_personeria:
-        Required for RDON; e.g. "719".
-    timeout:
-        HTTP request timeout in seconds (default 120).
-    session:
-        Optional ``requests.Session`` to use (useful for testing / mocking).
-    petroleo_rates:
-        Optional mapping of PETROLEO code → per-unit tax amount, e.g.
+    taxid : str
+        Fiscal ID / NIT of the issuer. Digits only or with separators
+        (e.g. ``"12345678"`` or ``"1234567-8"``); non-digits are stripped.
+        Internally padded to 12 chars.
+    username : str
+        Short Digifact username (the part after the ``GT.<NIT>.`` prefix,
+        e.g. ``"FELUSER"``).
+    password : str, optional
+        Account password. Required unless ``token`` is supplied.
+    environment : {"test", "production"}, default "test"
+        Target environment.
+    token : str, optional
+        Pre-obtained bearer token. If provided, login is skipped and
+        ``password`` is not needed.
+    seller_name : str, optional
+        Overrides the issuer display name. When empty, the SDK resolves it
+        from SAT via :meth:`lookup_nit`.
+    seller_address : str, optional
+        Overrides the issuer address. When empty, the SDK resolves it from
+        SAT via :meth:`lookup_nit`.
+    afiliacion_iva : {"GEN", "PEQ", "EXE"}, default "GEN"
+        IVA affiliation recorded in SAT RTU. "PEQ" = Pequeño Contribuyente,
+        "EXE" = Exento.
+    tipo_personeria : str, default "1"
+        ``TipoPersoneria`` code from the RTU (used by RDON).
+    tipo_frase : str, optional
+        Global override for ``TipoFrase`` (SAT ``AdditionlInfo``). When
+        ``None`` (default), the SDK uses :func:`default_frase` based on
+        DocType + afiliación. Can be overridden per-call.
+    escenario : str, optional
+        Global override for ``CodigoEscenario``. When ``None`` (default),
+        uses the defaults table. For GEN, common values are ``"1"`` (ISR
+        régimen sobre utilidades, default) or ``"2"`` (ISR opcional
+        simplificado sobre ingresos).
+    branch_code : str, default "1"
+        Código del establecimiento (SAT RTU). Each NIT may have several
+        establecimientos (1, 2, 3, …); ``"1"`` is usually the principal.
+    branch_name : str, default "ESTABLECIMIENTO PRINCIPAL"
+        Nombre comercial del establecimiento.
+    timeout : int, default 120
+        HTTP request timeout in seconds.
+    session : requests.Session, optional
+        Optional :class:`requests.Session` to use (useful for testing or
+        connection pooling).
+    petroleo_rates : dict[str, float], optional
+        Mapping of PETROLEO code → per-unit tax amount, e.g.
         ``{"1": 4.70, "2": 4.60, "4": 1.30}`` (SUPER/REGULAR/DIESEL).
         When set, fuel items in :meth:`fuel_invoice` that provide
         ``petroleo_code`` but omit ``petroleo_amount`` will have the amount
@@ -105,6 +127,8 @@ class DigifactClient:
         tipo_personeria: str = "1",
         tipo_frase: str | None = None,
         escenario: str | None = None,
+        branch_code: str = "1",
+        branch_name: str = "ESTABLECIMIENTO PRINCIPAL",
         timeout: int = 120,
         session: requests.Session | None = None,
         petroleo_rates: dict[str, float] | None = None,
@@ -125,6 +149,8 @@ class DigifactClient:
         self.tipo_personeria = tipo_personeria
         self.tipo_frase = tipo_frase
         self.escenario = escenario
+        self.branch_code = branch_code
+        self.branch_name = branch_name
         self.timeout = timeout
 
         base = _BASE_URLS.get(environment)
@@ -244,7 +270,19 @@ class DigifactClient:
 
     # ── Raw API calls ─────────────────────────────────────────────────────────
 
+    def _apply_branch_info(self, payload: dict) -> dict:
+        """Overlay configured ``branch_code`` / ``branch_name`` onto the
+        ``Seller.BranchInfo`` block so callers don't have to plumb it through
+        every builder.
+        """
+        branch = payload.get("Seller", {}).get("BranchInfo")
+        if isinstance(branch, dict):
+            branch["Code"] = self.branch_code
+            branch["Name"] = self.branch_name
+        return payload
+
     def _certify(self, payload: dict) -> dict:
+        payload = self._apply_branch_info(payload)
         resp = self._session.post(
             f"{self.base_url}/v2/transform/nuc_json",
             params={

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 2.2.2
+Version: 2.2.3
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -38,6 +38,27 @@ O desde el código fuente:
 pip install -e sdk/python/
 ```
 
+## Configuración del cliente (`DigifactClient(...)`)
+
+| 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()`. |
+| `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`. |
+| `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()`. |
+
 ## Inicio rápido
 
 ```python
@@ -282,6 +303,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)` | 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"}`. |
+| `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

{digifact_sdk-2.2.2 → digifact_sdk-2.2.3}/pyproject.toml

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