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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 3.1.0
+Version: 3.2.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -394,7 +394,9 @@ 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`.
+Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `series`, `number`, `issue_datetime`, `enrolled_timestamp`, `additional_info` (acuse de la SAT) y `raw`.
+
+`invoice()`, `cca_invoice()`, `fuel_invoice()`, `credit_note()` y `debit_note()` aceptan además `internal_reference` y `validate_internal_reference` (ver [Emisión sin duplicados](#emisión-sin-duplicados-referencia-interna)).
 
 | Método | Firma | Descripción |
 |--------|-------|-------------|
@@ -409,6 +411,7 @@ Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `
 | `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. |
+| `find_by_internal_reference()` | `find_by_internal_reference(reference, issued_on)` | DTE certificados con esa referencia interna ese día (`SHARED_GETDTEINFO_BY_INTERNALID`). Devuelve `list[dict]`, vacía si no hay. |
 
 ### Parámetros comunes
 
@@ -416,6 +419,39 @@ Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `
 - **`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": ...}`.
 
+## Emisión sin duplicados (referencia interna)
+
+Digifact guarda una referencia interna por DTE (el `Code` de la ADENDA). Con `validate_internal_reference=True`
+rechaza un segundo DTE con la misma referencia, así que un envío que se quedó sin respuesta se puede repetir sin
+emitir dos veces:
+
+```python
+import uuid
+from digifact_sdk import DigifactDuplicateReferenceError
+
+referencia = str(uuid.uuid4())  # un GUID; Digifact también acepta referencias más cortas
+try:
+    result = client.invoice("CF", items, internal_reference=referencia, validate_internal_reference=True)
+except DigifactDuplicateReferenceError:
+    # ya se había enviado: el DTE pudo quedar certificado
+    filas = client.find_by_internal_reference(referencia, issued_on="2026-11-03")
+```
+
+* Sin `internal_reference` el payload no cambia: se envía la referencia fija de siempre con `NO_VALIDAR`.
+* NCRE, NDEB, FCAM, FESP y CCA reciben una ADENDA mínima con la referencia, junto a su complemento.
+* `SHARED_GETDTEINFO_BY_INTERNALID` y el error `9022` no están en la documentación de Digifact para
+  Guatemala, pero se verificaron en el ambiente de pruebas el 3 de noviembre de 2026: el duplicado llega con
+  `code` 3000 y `[9022]` en la descripción, y la consulta encuentra el DTE sin prefijo en `DATA2`.
+
+## Token y reintentos
+
+* Si Digifact responde `401` (token vencido) y el cliente tiene `password`, el SDK inicia sesión otra vez y repite la
+  petición una sola vez. Con solo `token`, lanza `DigifactAuthError`.
+* `client.token` devuelve el token vigente, para guardarlo en un caché compartido y pasarlo como `token=` a otros
+  procesos.
+* Los errores HTTP traen `exc.code` (el estado HTTP) y `exc.retryable`: `True` para 5xx, `False` para 4xx (`400`,
+  `406` documento inválido, `415` tipo de contenido).
+
 ## Establecimiento (sucursal)
 
 Cada NIT puede tener varios establecimientos registrados en el RTU. Configúralos al crear el cliente:
@@ -460,7 +496,8 @@ python -m pytest tests/ -v
 from digifact_sdk import (
     DigifactError,          # base
     DigifactAuthError,      # fallo de autenticación
-    DigifactApiError,       # error HTTP / de API
+    DigifactApiError,       # error HTTP / de API (.retryable)
+    DigifactDuplicateReferenceError, # referencia interna ya enviada (9022)
     DigifactValidationError, # rechazo de SAT
     DigifactNitNotFoundError, # NIT no encontrado
 )

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

@@ -370,7 +370,9 @@ 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`.
+Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `series`, `number`, `issue_datetime`, `enrolled_timestamp`, `additional_info` (acuse de la SAT) y `raw`.
+
+`invoice()`, `cca_invoice()`, `fuel_invoice()`, `credit_note()` y `debit_note()` aceptan además `internal_reference` y `validate_internal_reference` (ver [Emisión sin duplicados](#emisión-sin-duplicados-referencia-interna)).
 
 | Método | Firma | Descripción |
 |--------|-------|-------------|
@@ -385,6 +387,7 @@ Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `
 | `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. |
+| `find_by_internal_reference()` | `find_by_internal_reference(reference, issued_on)` | DTE certificados con esa referencia interna ese día (`SHARED_GETDTEINFO_BY_INTERNALID`). Devuelve `list[dict]`, vacía si no hay. |
 
 ### Parámetros comunes
 
@@ -392,6 +395,39 @@ Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `
 - **`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": ...}`.
 
+## Emisión sin duplicados (referencia interna)
+
+Digifact guarda una referencia interna por DTE (el `Code` de la ADENDA). Con `validate_internal_reference=True`
+rechaza un segundo DTE con la misma referencia, así que un envío que se quedó sin respuesta se puede repetir sin
+emitir dos veces:
+
+```python
+import uuid
+from digifact_sdk import DigifactDuplicateReferenceError
+
+referencia = str(uuid.uuid4())  # un GUID; Digifact también acepta referencias más cortas
+try:
+    result = client.invoice("CF", items, internal_reference=referencia, validate_internal_reference=True)
+except DigifactDuplicateReferenceError:
+    # ya se había enviado: el DTE pudo quedar certificado
+    filas = client.find_by_internal_reference(referencia, issued_on="2026-11-03")
+```
+
+* Sin `internal_reference` el payload no cambia: se envía la referencia fija de siempre con `NO_VALIDAR`.
+* NCRE, NDEB, FCAM, FESP y CCA reciben una ADENDA mínima con la referencia, junto a su complemento.
+* `SHARED_GETDTEINFO_BY_INTERNALID` y el error `9022` no están en la documentación de Digifact para
+  Guatemala, pero se verificaron en el ambiente de pruebas el 3 de noviembre de 2026: el duplicado llega con
+  `code` 3000 y `[9022]` en la descripción, y la consulta encuentra el DTE sin prefijo en `DATA2`.
+
+## Token y reintentos
+
+* Si Digifact responde `401` (token vencido) y el cliente tiene `password`, el SDK inicia sesión otra vez y repite la
+  petición una sola vez. Con solo `token`, lanza `DigifactAuthError`.
+* `client.token` devuelve el token vigente, para guardarlo en un caché compartido y pasarlo como `token=` a otros
+  procesos.
+* Los errores HTTP traen `exc.code` (el estado HTTP) y `exc.retryable`: `True` para 5xx, `False` para 4xx (`400`,
+  `406` documento inválido, `415` tipo de contenido).
+
 ## Establecimiento (sucursal)
 
 Cada NIT puede tener varios establecimientos registrados en el RTU. Configúralos al crear el cliente:
@@ -436,7 +472,8 @@ python -m pytest tests/ -v
 from digifact_sdk import (
     DigifactError,          # base
     DigifactAuthError,      # fallo de autenticación
-    DigifactApiError,       # error HTTP / de API
+    DigifactApiError,       # error HTTP / de API (.retryable)
+    DigifactDuplicateReferenceError, # referencia interna ya enviada (9022)
     DigifactValidationError, # rechazo de SAT
     DigifactNitNotFoundError, # NIT no encontrado
 )

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

@@ -11,18 +11,20 @@ from .client import DigifactClient, DteResult
 from .exceptions import (
     DigifactApiError,
     DigifactAuthError,
+    DigifactDuplicateReferenceError,
     DigifactError,
     DigifactNitNotFoundError,
     DigifactValidationError,
 )
 
-__version__ = "3.1.0"
+__version__ = "3.2.0"
 __all__ = [
     "DigifactClient",
     "DteResult",
     "DigifactError",
     "DigifactAuthError",
     "DigifactApiError",
+    "DigifactDuplicateReferenceError",
     "DigifactValidationError",
     "DigifactNitNotFoundError",
     "FuelExemption",

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

@@ -28,6 +28,32 @@ def _adenda_code(doc_type: str) -> str:
     return ADENDA_CODE_ALT if doc_type in _ALT_ADENDA_TYPES else ADENDA_CODE_STD
 
 
+VALIDATE_REFERENCE = "VALIDAR"
+SKIP_REFERENCE_VALIDATION = "NO_VALIDAR"
+_VALIDATION_FLAG = "VALIDAR_REFERENCIA_INTERNA"
+
+
+def apply_internal_reference(payload: dict, reference: str, *, validate: bool) -> dict:
+    """Set the Digifact internal reference (ADENDA ``Code``) of a built payload.
+
+    With ``validate=True`` Digifact rejects a second DTE with the same
+    reference (error 9022), which makes retries safe. DTE types whose builder
+    carries no ADENDA (NCRE, NDEB, FCAM, FESP, CCA) get a minimal one.
+    """
+    flag = {"Name": _VALIDATION_FLAG, "Data": None, "Value": VALIDATE_REFERENCE if validate else SKIP_REFERENCE_VALIDATION}
+    document_info = payload.get("AdditionalDocumentInfo") or {}
+    entries = document_info.setdefault("AdditionalInfo", [])
+    adenda = next((entry for entry in entries if entry.get("Type") == "ADENDA"), None)
+    if adenda is None:
+        entries.append({"Code": reference, "Type": "ADENDA", "AditionalInfo": [flag]})
+    else:
+        adenda["Code"] = reference
+        others = [info for info in adenda.get("AditionalInfo") or [] if info.get("Name") != _VALIDATION_FLAG]
+        adenda["AditionalInfo"] = [flag, *others]
+    payload["AdditionalDocumentInfo"] = document_info
+    return payload
+
+
 # ── Exención temporal de combustibles (Decreto 22-2026) ──────────────────────
 FUEL_EXEMPT_SUPER = "18"
 FUEL_EXEMPT_REGULAR_IMPORTER = "19"

{digifact_sdk-3.1.0 → digifact_sdk-3.2.0}/digifact_sdk/client.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass, field
+from datetime import date
 from decimal import Decimal
 from typing import Any
 
@@ -18,6 +19,7 @@ from .builder import (
     build_nabn,
     build_ncre,
     build_ndeb,
+    apply_internal_reference,
     build_rdon,
     build_reci,
     default_frase,
@@ -29,6 +31,7 @@ from .builder import (
 from .exceptions import (
     DigifactApiError,
     DigifactAuthError,
+    DigifactDuplicateReferenceError,
     DigifactError,
     DigifactNitNotFoundError,
     DigifactValidationError,
@@ -44,6 +47,11 @@ _BASE_URLS = {
 # Digits in a Guatemalan CUI (DPI); a NIT never reaches this length.
 CUI_LENGTH = 13
 
+HTTP_UNAUTHORIZED = 401
+DUPLICATE_REFERENCE_CODE = 9022
+DUPLICATE_REFERENCE_GLOBAL_CODE = "BUS-003"
+DUPLICATE_REFERENCE_MESSAGE = "ENVIADA A CERTIFICAR"
+
 
 @dataclass
 class DteResult:
@@ -54,6 +62,8 @@ class DteResult:
     number: str
     issue_datetime: str
     raw: dict = field(default_factory=dict)
+    enrolled_timestamp: str = ""
+    additional_info: dict = field(default_factory=dict)
 
     @property
     def auth_number_upper(self) -> str:
@@ -182,6 +192,11 @@ class DigifactClient:
         env = self.environment
         return f"DigifactClient(taxid={self.taxid!r}, username={self.username!r}, environment={env!r})"
 
+    @property
+    def token(self) -> str:
+        """Current bearer token ("" before the first login), to cache it across processes."""
+        return self._token
+
     # ── Authentication ────────────────────────────────────────────────────────
 
     def _login(self) -> str:
@@ -208,6 +223,22 @@ class DigifactClient:
     def _headers(self) -> dict:
         return {"Authorization": self._login(), "Content-Type": "application/json"}
 
+    def _send(self, verb: str, url: str, *, json_content: bool = True, **kwargs: Any) -> requests.Response:
+        """Send an authenticated request, logging in again once if the token expired (401)."""
+        send = getattr(self._session, verb)
+        resp = send(url, headers=self._auth_headers(json_content), timeout=self.timeout, **kwargs)
+        if resp.status_code == HTTP_UNAUTHORIZED and self.password:
+            self._token = ""
+            resp = send(url, headers=self._auth_headers(json_content), timeout=self.timeout, **kwargs)
+        if resp.status_code == HTTP_UNAUTHORIZED:
+            raise DigifactAuthError(
+                "Digifact rejected the token (401)", code=HTTP_UNAUTHORIZED, raw=_try_json(resp)
+            )
+        return resp
+
+    def _auth_headers(self, json_content: bool) -> dict:
+        return self._headers() if json_content else {"Authorization": self._login()}
+
     # ── Seller info ───────────────────────────────────────────────────────────
 
     def _get_seller_info(self) -> tuple[str, str]:
@@ -302,23 +333,31 @@ class DigifactClient:
             branch["Name"] = self.branch_name
         return payload
 
-    def _certify(self, payload: dict) -> dict:
+    def _certify(
+        self,
+        payload: dict,
+        *,
+        internal_reference: str | None = None,
+        validate_internal_reference: bool = False,
+    ) -> dict:
         payload = self._apply_branch_info(payload)
-        resp = self._session.post(
+        if internal_reference:
+            payload = apply_internal_reference(
+                payload, internal_reference, validate=validate_internal_reference
+            )
+        elif validate_internal_reference:
+            raise ValueError("validate_internal_reference requires internal_reference")
+        resp = self._send(
+            "post",
             f"{self.base_url}/v2/transform/nuc_json",
             params={
                 "TAXID": self.padded_taxid,
                 "FORMAT": "XML|HTML|PDF",
                 "USERNAME": self.username,
             },
-            headers=self._headers(),
             json=payload,
-            timeout=self.timeout,
         )
-        try:
-            resp.raise_for_status()
-        except requests.HTTPError as exc:
-            raise DigifactApiError(f"Certify HTTP error: {exc}", raw=_try_json(resp)) from exc
+        _raise_for_status(resp, "Certify")
         data = resp.json()
         return _check_response(data)
 
@@ -328,12 +367,15 @@ class DigifactClient:
         number = str(data.get("serial") or data.get("Numero") or "")
         ts_raw = data.get("issuedTimeStamp") or data.get("FechaEmision") or ""
         issue_dt = ts_raw.replace("T", " ") if "T" in ts_raw else ts_raw
+        additional = data.get("additionalInfo")
         return DteResult(
             auth_number=auth,
             series=series,
             number=number,
             issue_datetime=issue_dt,
             raw=data,
+            enrolled_timestamp=data.get("enrolledTimeStamp") or "",
+            additional_info=additional if isinstance(additional, dict) else {},
         )
 
     # ── Public DTE methods ────────────────────────────────────────────────────
@@ -368,6 +410,8 @@ class DigifactClient:
         tipo_personeria: str | None = None,
         tipo_frase: str | None = None,
         escenario: str | None = None,
+        internal_reference: str | None = None,
+        validate_internal_reference: bool = False,
     ) -> DteResult:
         """Emit a DTE invoice (FACT, FCAM, NABN, FESP, RDON, FPEQ, RECI, CCA).
 
@@ -387,6 +431,13 @@ class DigifactClient:
             Observations text for ADENDA.
         tipo_personeria:
             Required for RDON.
+        internal_reference:
+            Digifact internal reference (ADENDA ``Code``). Digifact suggests a
+            GUID, but shorter references are accepted. Can be queried with :meth:`find_by_internal_reference`.
+        validate_internal_reference:
+            When True, Digifact rejects a second DTE with the same
+            ``internal_reference`` (:class:`DigifactDuplicateReferenceError`), so a
+            timed-out request can be retried without issuing twice.
         """
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
@@ -493,7 +544,11 @@ class DigifactClient:
                 observaciones=observaciones,
             )
 
-        data = self._certify(payload)
+        data = self._certify(
+            payload,
+            internal_reference=internal_reference,
+            validate_internal_reference=validate_internal_reference,
+        )
         return self._parse_result(data)
 
     def cca_invoice(
@@ -504,8 +559,13 @@ class DigifactClient:
         *,
         tipo_frase: str | None = None,
         escenario: str | None = None,
+        internal_reference: str | None = None,
+        validate_internal_reference: bool = False,
     ) -> DteResult:
-        """Emit a CCA (Cobro por Cuenta Ajena) FACT+CCA complemento."""
+        """Emit a CCA (Cobro por Cuenta Ajena) FACT+CCA complemento.
+
+        ``internal_reference`` and ``validate_internal_reference`` work as in :meth:`invoice`.
+        """
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
         if self.frases is not None and tipo_frase is None and escenario is None:
@@ -526,7 +586,11 @@ class DigifactClient:
             escenario=es,
             frases=eff_frases,
         )
-        data = self._certify(payload)
+        data = self._certify(
+            payload,
+            internal_reference=internal_reference,
+            validate_internal_reference=validate_internal_reference,
+        )
         return self._parse_result(data)
 
     def fuel_invoice(
@@ -537,6 +601,8 @@ class DigifactClient:
         tipo_frase: str | None = None,
         escenario: str | None = None,
         frases: list[dict] | None = None,
+        internal_reference: str | None = None,
+        validate_internal_reference: bool = False,
     ) -> DteResult:
         """Emit a combustible (fuel) FACT invoice.
 
@@ -569,6 +635,13 @@ class DigifactClient:
                 frases=[{"tipo_frase": "1", "escenario": "1"},
                         {"tipo_frase": "9", "escenario": "18"},
                         {"tipo_frase": "9", "escenario": "19"}]
+        internal_reference:
+            Digifact internal reference (ADENDA ``Code``). Digifact suggests a
+            GUID, but shorter references are accepted. Can be queried with :meth:`find_by_internal_reference`.
+        validate_internal_reference:
+            When True, Digifact rejects a second DTE with the same
+            ``internal_reference`` (:class:`DigifactDuplicateReferenceError`), so a
+            timed-out request can be retried without issuing twice.
 
         Example::
 
@@ -612,7 +685,11 @@ class DigifactClient:
             escenario=eff_es,
             frases=eff_frases,
         )
-        data = self._certify(payload)
+        data = self._certify(
+            payload,
+            internal_reference=internal_reference,
+            validate_internal_reference=validate_internal_reference,
+        )
         return self._parse_result(data)
 
     def _apply_petroleo_rates(self, items: list[dict]) -> list[dict]:
@@ -644,6 +721,8 @@ class DigifactClient:
         *,
         tipo_frase: str | None = None,
         escenario: str | None = None,
+        internal_reference: str | None = None,
+        validate_internal_reference: bool = False,
     ) -> DteResult:
         """Emit a NCRE (Nota de Crédito).
 
@@ -653,6 +732,13 @@ class DigifactClient:
             {"auth_number": str, "date": "YYYY-MM-DD", "series": str, "number": str|int}
         reason:
             Reason for the credit note.
+        internal_reference:
+            Digifact internal reference (ADENDA ``Code``). Digifact suggests a
+            GUID, but shorter references are accepted. Can be queried with :meth:`find_by_internal_reference`.
+        validate_internal_reference:
+            When True, Digifact rejects a second DTE with the same
+            ``internal_reference`` (:class:`DigifactDuplicateReferenceError`), so a
+            timed-out request can be retried without issuing twice.
         """
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
@@ -675,7 +761,11 @@ class DigifactClient:
             escenario=es,
             frases=eff_frases,
         )
-        data = self._certify(payload)
+        data = self._certify(
+            payload,
+            internal_reference=internal_reference,
+            validate_internal_reference=validate_internal_reference,
+        )
         return self._parse_result(data)
 
     def debit_note(
@@ -687,6 +777,8 @@ class DigifactClient:
         *,
         tipo_frase: str | None = None,
         escenario: str | None = None,
+        internal_reference: str | None = None,
+        validate_internal_reference: bool = False,
     ) -> DteResult:
         """Emit a NDEB (Nota de Débito).
 
@@ -696,6 +788,13 @@ class DigifactClient:
             {"auth_number": str, "date": "YYYY-MM-DD", "series": str, "number": str|int}
         reason:
             Reason for the debit note.
+        internal_reference:
+            Digifact internal reference (ADENDA ``Code``). Digifact suggests a
+            GUID, but shorter references are accepted. Can be queried with :meth:`find_by_internal_reference`.
+        validate_internal_reference:
+            When True, Digifact rejects a second DTE with the same
+            ``internal_reference`` (:class:`DigifactDuplicateReferenceError`), so a
+            timed-out request can be retried without issuing twice.
         """
         seller_name, seller_address = self._get_seller_info()
         buyer_dict = self._resolve_buyer(buyer)
@@ -718,7 +817,11 @@ class DigifactClient:
             escenario=es,
             frases=eff_frases,
         )
-        data = self._certify(payload)
+        data = self._certify(
+            payload,
+            internal_reference=internal_reference,
+            validate_internal_reference=validate_internal_reference,
+        )
         return self._parse_result(data)
 
     def cancel(
@@ -735,9 +838,9 @@ class DigifactClient:
         issue_datetime:
             Format "YYYY-MM-DD HH:MM:SS"
         """
-        resp = self._session.post(
+        resp = self._send(
+            "post",
             f"{self.base_url}/CancelFelGT",
-            headers=self._headers(),
             json={
                 "Taxid": self.taxid,
                 "Autorizacion": auth_number,
@@ -746,12 +849,8 @@ class DigifactClient:
                 "MotivoAnulacion": reason,
                 "Username": self.username,
             },
-            timeout=self.timeout,
         )
-        try:
-            resp.raise_for_status()
-        except requests.HTTPError as exc:
-            raise DigifactApiError(f"Cancel HTTP error: {exc}", raw=_try_json(resp)) from exc
+        _raise_for_status(resp, "Cancel")
         return resp.json()
 
     def credit_note_total(
@@ -768,9 +867,9 @@ class DigifactClient:
         issue_datetime:
             Format "YYYY-MM-DD HH:MM:SS"
         """
-        resp = self._session.post(
+        resp = self._send(
+            "post",
             f"{self.base_url}/cert/ncredtotal",
-            headers=self._headers(),
             json={
                 "Staxid": self.taxid,
                 "Authnumber": auth_number,
@@ -780,14 +879,8 @@ class DigifactClient:
                 "Formatos": "xml|html|pdf",
                 "Username": self.username,
             },
-            timeout=self.timeout,
         )
-        try:
-            resp.raise_for_status()
-        except requests.HTTPError as exc:
-            raise DigifactApiError(
-                f"NcredTotal HTTP error: {exc}", raw=_try_json(resp)
-            ) from exc
+        _raise_for_status(resp, "NcredTotal")
         return resp.json()
 
     # ── Query methods ─────────────────────────────────────────────────────────
@@ -802,8 +895,10 @@ class DigifactClient:
         if digits in self._nit_cache:
             return self._nit_cache[digits]
 
-        resp = self._session.get(
+        resp = self._send(
+            "get",
             f"{self.base_url}/Shared",
+            json_content=False,
             params={
                 "COUNTRY": "GT",
                 "TAXID": self.padded_taxid,
@@ -811,15 +906,8 @@ class DigifactClient:
                 "DATA2": f"NIT|{digits}",
                 "USERNAME": self.username,
             },
-            headers={"Authorization": self._login()},
-            timeout=self.timeout,
         )
-        try:
-            resp.raise_for_status()
-        except requests.HTTPError as exc:
-            raise DigifactApiError(
-                f"NIT lookup HTTP error: {exc}", raw=_try_json(resp)
-            ) from exc
+        _raise_for_status(resp, "NIT lookup")
 
         data = resp.json()
         normalized = _parse_nit_response(digits, data)
@@ -838,8 +926,10 @@ class DigifactClient:
         if digits in self._cui_cache:
             return self._cui_cache[digits]
 
-        resp = self._session.get(
+        resp = self._send(
+            "get",
             f"{self.base_url}/Shared",
+            json_content=False,
             params={
                 "COUNTRY": "GT",
                 "TAXID": self.padded_taxid,
@@ -847,15 +937,8 @@ class DigifactClient:
                 "DATA2": f"CUI|{digits}",
                 "USERNAME": self.username,
             },
-            headers={"Authorization": self._login()},
-            timeout=self.timeout,
         )
-        try:
-            resp.raise_for_status()
-        except requests.HTTPError as exc:
-            raise DigifactApiError(
-                f"CUI lookup HTTP error: {exc}", raw=_try_json(resp)
-            ) from exc
+        _raise_for_status(resp, "CUI lookup")
 
         data = resp.json()
         normalized = _parse_cui_response(digits, data)
@@ -866,8 +949,10 @@ class DigifactClient:
 
     def get_dte_info(self, auth_number: str) -> dict:
         """Get DTE info via SHARED_GETDTEINFO."""
-        resp = self._session.get(
+        resp = self._send(
+            "get",
             f"{self.base_url}/Shared",
+            json_content=False,
             params={
                 "COUNTRY": "GT",
                 "TAXID": self.padded_taxid,
@@ -875,41 +960,92 @@ class DigifactClient:
                 "DATA2": f"AUTHNUMBER|{auth_number}",
                 "USERNAME": self.username,
             },
-            headers={"Authorization": self._login()},
-            timeout=self.timeout,
         )
+        _raise_for_status(resp, "GetDteInfo")
+        return resp.json()
+
+    def find_by_internal_reference(self, reference: str, issued_on: date | str) -> list[dict]:
+        """Find the DTEs certified with an internal reference on a given day.
+
+        Uses ``SHARED_GETDTEINFO_BY_INTERNALID``. Returns the ``RESPONSE`` rows
+        (``GUID``, ``SERIE``, ``NUMERO``, ``ESTATUS``…), or an empty list when
+        Digifact has no DTE with that reference on that day. A reply that is not
+        JSON raises a retryable :class:`DigifactApiError` instead of looking empty.
+
+        Parameters
+        ----------
+        issued_on:
+            Issue date, as a :class:`datetime.date` or "YYYY-MM-DD".
+        """
+        day = issued_on.isoformat() if isinstance(issued_on, date) else issued_on
+        resp = self._send(
+            "get",
+            f"{self.base_url}/Shared",
+            json_content=False,
+            params={
+                "COUNTRY": "GT",
+                "TAXID": self.padded_taxid,
+                "DATA1": "SHARED_GETDTEINFO_BY_INTERNALID",
+                "DATA2": f"REFERENCIA_INTERNA|{reference}|ISSUEDDATE|{day}",
+                "USERNAME": self.username,
+            },
+        )
+        _raise_for_status(resp, "GetDteInfoByInternalId")
         try:
-            resp.raise_for_status()
-        except requests.HTTPError as exc:
+            data = resp.json()
+        except ValueError as exc:
             raise DigifactApiError(
-                f"GetDteInfo HTTP error: {exc}", raw=_try_json(resp)
+                "GetDteInfoByInternalId returned a response that is not JSON",
+                code=resp.status_code,
+                raw={"_text": resp.text},
+                retryable=True,
             ) from exc
-        return resp.json()
+        rows = data.get("RESPONSE") if isinstance(data, dict) else None
+        return [row for row in rows if isinstance(row, dict)] if isinstance(rows, list) else []
 
     def get_dte(self, auth_number: str, fmt: str = "JSON") -> dict:
         """Retrieve a DTE document via GET /GetDocument."""
-        resp = self._session.get(
+        resp = self._send(
+            "get",
             f"{self.base_url}/GetDocument",
+            json_content=False,
             params={
                 "AUTHNUMBER": auth_number,
                 "TAXID": self.padded_taxid,
                 "FORMAT": fmt,
                 "USERNAME": self.username,
             },
-            headers={"Authorization": self._login()},
-            timeout=self.timeout,
         )
-        try:
-            resp.raise_for_status()
-        except requests.HTTPError as exc:
-            raise DigifactApiError(
-                f"GetDocument HTTP error: {exc}", raw=_try_json(resp)
-            ) from exc
+        _raise_for_status(resp, "GetDocument")
         return resp.json()
 
 
 # ── Internal helpers ──────────────────────────────────────────────────────────
 
+def _raise_for_status(resp: requests.Response, operation: str) -> None:
+    try:
+        resp.raise_for_status()
+    except requests.HTTPError as exc:
+        raise DigifactApiError(
+            f"{operation} HTTP error: {exc}",
+            code=resp.status_code,
+            raw=_try_json(resp),
+            retryable=resp.status_code >= 500,
+        ) from exc
+
+
+def _is_duplicate_reference(data: dict, code: Any) -> bool:
+    if str(code) == str(DUPLICATE_REFERENCE_CODE):
+        return True
+    global_code = str(data.get("codeError") or "").upper()
+    message = str(data.get("description") or data.get("message") or "").upper()
+    return (
+        DUPLICATE_REFERENCE_GLOBAL_CODE in global_code
+        or str(DUPLICATE_REFERENCE_CODE) in message
+        or DUPLICATE_REFERENCE_MESSAGE in message
+    )
+
+
 def _try_json(resp: requests.Response) -> dict:
     try:
         return resp.json()
@@ -928,7 +1064,15 @@ def _check_response(data: dict) -> dict:
         # Unknown format — return as-is (let caller decide)
         return data
 
-    code_int = int(code)
+    if _is_duplicate_reference(data, code):
+        msg = data.get("description") or data.get("message") or str(data)
+        raise DigifactDuplicateReferenceError(
+            f"Internal reference already sent to certify: {msg}", code=DUPLICATE_REFERENCE_CODE, raw=data
+        )
+    try:
+        code_int = int(code)
+    except (TypeError, ValueError):
+        raise DigifactApiError(f"API returned an unexpected code {code!r}: {data}", raw=data) from None
     if code_int == 1:
         return data
     if code_int == 0:

{digifact_sdk-3.1.0 → digifact_sdk-3.2.0}/digifact_sdk/exceptions.py

@@ -5,10 +5,18 @@ from __future__ import annotations
 class DigifactError(Exception):
     """Base exception for all Digifact SDK errors."""
 
-    def __init__(self, message: str, code: int | None = None, raw: dict | None = None) -> None:
+    def __init__(
+        self,
+        message: str,
+        code: int | None = None,
+        raw: dict | None = None,
+        *,
+        retryable: bool = False,
+    ) -> None:
         super().__init__(message)
         self.code = code
         self.raw = raw or {}
+        self.retryable = retryable
 
     def __repr__(self) -> str:
         return f"DigifactError(message={str(self)!r}, code={self.code!r})"
@@ -22,6 +30,15 @@ class DigifactApiError(DigifactError):
     """API returned a non-success response."""
 
 
+class DigifactDuplicateReferenceError(DigifactApiError):
+    """The internal reference was already sent to certify (Digifact 9022 / BUS-003).
+
+    Raised only when the DTE was sent with ``validate_internal_reference=True``.
+    The original DTE may already be certified: look it up with
+    :meth:`DigifactClient.find_by_internal_reference` instead of issuing again.
+    """
+
+
 class DigifactValidationError(DigifactError):
     """Payload validation error (SAT or Digifact rejection)."""
 

{digifact_sdk-3.1.0 → digifact_sdk-3.2.0}/digifact_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digifact-sdk
-Version: 3.1.0
+Version: 3.2.0
 Summary: Python SDK for Digifact FEL Guatemala e-invoicing API
 Author-email: AALONZOLU <noreply@github.com>
 License: MIT
@@ -394,7 +394,9 @@ 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`.
+Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `series`, `number`, `issue_datetime`, `enrolled_timestamp`, `additional_info` (acuse de la SAT) y `raw`.
+
+`invoice()`, `cca_invoice()`, `fuel_invoice()`, `credit_note()` y `debit_note()` aceptan además `internal_reference` y `validate_internal_reference` (ver [Emisión sin duplicados](#emisión-sin-duplicados-referencia-interna)).
 
 | Método | Firma | Descripción |
 |--------|-------|-------------|
@@ -409,6 +411,7 @@ Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `
 | `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. |
+| `find_by_internal_reference()` | `find_by_internal_reference(reference, issued_on)` | DTE certificados con esa referencia interna ese día (`SHARED_GETDTEINFO_BY_INTERNALID`). Devuelve `list[dict]`, vacía si no hay. |
 
 ### Parámetros comunes
 
@@ -416,6 +419,39 @@ Todos los métodos de emisión devuelven `DteResult` con `result.auth_number`, `
 - **`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": ...}`.
 
+## Emisión sin duplicados (referencia interna)
+
+Digifact guarda una referencia interna por DTE (el `Code` de la ADENDA). Con `validate_internal_reference=True`
+rechaza un segundo DTE con la misma referencia, así que un envío que se quedó sin respuesta se puede repetir sin
+emitir dos veces:
+
+```python
+import uuid
+from digifact_sdk import DigifactDuplicateReferenceError
+
+referencia = str(uuid.uuid4())  # un GUID; Digifact también acepta referencias más cortas
+try:
+    result = client.invoice("CF", items, internal_reference=referencia, validate_internal_reference=True)
+except DigifactDuplicateReferenceError:
+    # ya se había enviado: el DTE pudo quedar certificado
+    filas = client.find_by_internal_reference(referencia, issued_on="2026-11-03")
+```
+
+* Sin `internal_reference` el payload no cambia: se envía la referencia fija de siempre con `NO_VALIDAR`.
+* NCRE, NDEB, FCAM, FESP y CCA reciben una ADENDA mínima con la referencia, junto a su complemento.
+* `SHARED_GETDTEINFO_BY_INTERNALID` y el error `9022` no están en la documentación de Digifact para
+  Guatemala, pero se verificaron en el ambiente de pruebas el 3 de noviembre de 2026: el duplicado llega con
+  `code` 3000 y `[9022]` en la descripción, y la consulta encuentra el DTE sin prefijo en `DATA2`.
+
+## Token y reintentos
+
+* Si Digifact responde `401` (token vencido) y el cliente tiene `password`, el SDK inicia sesión otra vez y repite la
+  petición una sola vez. Con solo `token`, lanza `DigifactAuthError`.
+* `client.token` devuelve el token vigente, para guardarlo en un caché compartido y pasarlo como `token=` a otros
+  procesos.
+* Los errores HTTP traen `exc.code` (el estado HTTP) y `exc.retryable`: `True` para 5xx, `False` para 4xx (`400`,
+  `406` documento inválido, `415` tipo de contenido).
+
 ## Establecimiento (sucursal)
 
 Cada NIT puede tener varios establecimientos registrados en el RTU. Configúralos al crear el cliente:
@@ -460,7 +496,8 @@ python -m pytest tests/ -v
 from digifact_sdk import (
     DigifactError,          # base
     DigifactAuthError,      # fallo de autenticación
-    DigifactApiError,       # error HTTP / de API
+    DigifactApiError,       # error HTTP / de API (.retryable)
+    DigifactDuplicateReferenceError, # referencia interna ya enviada (9022)
     DigifactValidationError, # rechazo de SAT
     DigifactNitNotFoundError, # NIT no encontrado
 )

{digifact_sdk-3.1.0 → digifact_sdk-3.2.0}/digifact_sdk.egg-info/SOURCES.txt

@@ -10,4 +10,5 @@ digifact_sdk.egg-info/SOURCES.txt
 digifact_sdk.egg-info/dependency_links.txt
 digifact_sdk.egg-info/requires.txt
 digifact_sdk.egg-info/top_level.txt
-tests/test_integration.py
+tests/test_integration.py
+tests/test_resilience.py

{digifact_sdk-3.1.0 → digifact_sdk-3.2.0}/pyproject.toml

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

digifact_sdk-3.2.0/tests/test_resilience.py

@@ -0,0 +1,241 @@
+"""Unit tests (no credentials) for internal references, token renewal and error classification."""
+from __future__ import annotations
+
+import json
+import unittest
+from collections import defaultdict, deque
+
+import requests
+
+from digifact_sdk import DigifactApiError, DigifactAuthError, DigifactClient, DigifactDuplicateReferenceError
+from digifact_sdk.builder import ADENDA_CODE_STD
+
+REFERENCE = "0F8FAD5B-D9CB-469F-A165-70867728950E"
+ITEMS = [{"description": "Servicio", "qty": 1, "price": 100}]
+ORIGIN = {"auth_number": "AAAABBBB-1111-2222-3333-444455556666", "date": "2026-10-01", "series": "AAAABBBB", "number": "1"}
+CERTIFIED = {
+    "code": 1,
+    "authNumber": "CCCCDDDD-1111-2222-3333-444455556666",
+    "batch": "CCCCDDDD",
+    "serial": 123,
+    "issuedTimeStamp": "2026-11-03T10:00:00",
+    "enrolledTimeStamp": "2026-11-03T10:00:02",
+    "additionalInfo": {"acuseReciboSAT": "ACEPTADO"},
+}
+
+
+def response(status: int, body: dict | str) -> requests.Response:
+    resp = requests.Response()
+    resp.status_code = status
+    resp._content = (body if isinstance(body, str) else json.dumps(body)).encode()
+    resp.headers["Content-Type"] = "application/json"
+    resp.url = "https://testnucgt.digifact.com/api"
+    return resp
+
+
+class FakeSession:
+    def __init__(self) -> None:
+        self.routes: dict[tuple[str, str], deque[requests.Response]] = defaultdict(deque)
+        self.calls: list[tuple[str, str, dict]] = []
+
+    def on(self, verb: str, path: str, *responses: requests.Response) -> FakeSession:
+        self.routes[(verb, path)].extend(responses)
+        return self
+
+    def calls_to(self, verb: str, path: str) -> list[dict]:
+        return [kwargs for called_verb, url, kwargs in self.calls if called_verb == verb and url.endswith(path)]
+
+    def post(self, url: str, **kwargs) -> requests.Response:
+        return self._respond("post", url, kwargs)
+
+    def get(self, url: str, **kwargs) -> requests.Response:
+        return self._respond("get", url, kwargs)
+
+    def _respond(self, verb: str, url: str, kwargs: dict) -> requests.Response:
+        self.calls.append((verb, url, kwargs))
+        for (route_verb, path), queue in self.routes.items():
+            if route_verb == verb and url.endswith(path):
+                return queue.popleft() if len(queue) > 1 else queue[0]
+        raise AssertionError(f"Unexpected {verb.upper()} {url}")
+
+
+def a_client(session: FakeSession, *, password: str = "secreto", token: str = "token-vigente") -> DigifactClient:
+    return DigifactClient(
+        taxid="12345678",
+        username="FELUSER",
+        password=password,
+        token=token,
+        seller_name="EMPRESA DEMO, SOCIEDAD ANONIMA",
+        seller_address="CIUDAD",
+        session=session,
+    )
+
+
+def adenda_of(payload: dict) -> list[dict]:
+    return [entry for entry in payload["AdditionalDocumentInfo"]["AdditionalInfo"] if entry["Type"] == "ADENDA"]
+
+
+def reference_flag(adenda: dict) -> str:
+    return next(info["Value"] for info in adenda["AditionalInfo"] if info["Name"] == "VALIDAR_REFERENCIA_INTERNA")
+
+
+class TestInternalReferenceUnit(unittest.TestCase):
+    def setUp(self) -> None:
+        self.session = FakeSession().on("post", "/v2/transform/nuc_json", response(200, CERTIFIED))
+        self.client = a_client(self.session)
+
+    def sent_payload(self) -> dict:
+        return self.session.calls_to("post", "/v2/transform/nuc_json")[-1]["json"]
+
+    def test_invoice_carries_the_reference_with_validation(self):
+        self.client.invoice("CF", ITEMS, internal_reference=REFERENCE, validate_internal_reference=True)
+
+        [adenda] = adenda_of(self.sent_payload())
+        self.assertEqual(adenda["Code"], REFERENCE)
+        self.assertEqual(reference_flag(adenda), "VALIDAR")
+        self.assertIn("AditionalData", adenda)
+
+    def test_reference_without_validation_is_only_stored(self):
+        self.client.invoice("CF", ITEMS, internal_reference=REFERENCE)
+
+        [adenda] = adenda_of(self.sent_payload())
+        self.assertEqual(adenda["Code"], REFERENCE)
+        self.assertEqual(reference_flag(adenda), "NO_VALIDAR")
+
+    def test_without_reference_the_payload_is_unchanged(self):
+        self.client.invoice("CF", ITEMS)
+
+        [adenda] = adenda_of(self.sent_payload())
+        self.assertEqual(adenda["Code"], ADENDA_CODE_STD)
+        self.assertEqual(reference_flag(adenda), "NO_VALIDAR")
+
+    def test_credit_note_gets_an_adenda_next_to_its_complement(self):
+        self.client.credit_note("CF", ITEMS, ORIGIN, "Devolución", internal_reference=REFERENCE,
+                                validate_internal_reference=True)
+
+        entries = self.sent_payload()["AdditionalDocumentInfo"]["AdditionalInfo"]
+        self.assertEqual([entry["Type"] for entry in entries], ["COMPLEMENTO", "ADENDA"])
+        self.assertEqual(entries[1]["Code"], REFERENCE)
+        self.assertEqual(reference_flag(entries[1]), "VALIDAR")
+
+    def test_validation_needs_a_reference(self):
+        with self.assertRaises(ValueError):
+            self.client.invoice("CF", ITEMS, validate_internal_reference=True)
+
+    def test_result_exposes_enrollment_and_additional_info(self):
+        result = self.client.invoice("CF", ITEMS)
+
+        self.assertEqual(result.enrolled_timestamp, "2026-11-03T10:00:02")
+        self.assertEqual(result.additional_info, {"acuseReciboSAT": "ACEPTADO"})
+
+
+class TestDuplicateReferenceUnit(unittest.TestCase):
+    def certify_answering(self, body: dict) -> None:
+        session = FakeSession().on("post", "/v2/transform/nuc_json", response(200, body))
+        a_client(session).invoice("CF", ITEMS, internal_reference=REFERENCE, validate_internal_reference=True)
+
+    def test_code_9022_is_a_duplicate_reference(self):
+        with self.assertRaises(DigifactDuplicateReferenceError) as raised:
+            self.certify_answering({"code": 9022, "description": "Referencia interna duplicada"})
+        self.assertFalse(raised.exception.retryable)
+
+    def test_rejection_message_about_an_already_sent_reference_is_a_duplicate(self):
+        with self.assertRaises(DigifactDuplicateReferenceError):
+            self.certify_answering({"code": 0, "description": "La referencia interna ya ha sido enviada a certificar"})
+
+    def test_global_error_code_bus_003_is_a_duplicate(self):
+        with self.assertRaises(DigifactDuplicateReferenceError):
+            self.certify_answering({"code": 0, "codeError": "BUS-003", "description": "Rechazado"})
+
+    def test_the_response_digifact_actually_sends_is_a_duplicate(self):
+        with self.assertRaises(DigifactDuplicateReferenceError):
+            self.certify_answering({"code": 3000, "message": "La referencia INTERNA, ya ha sido enviada a certificar",
+                                    "description": "[9022] - El documento bajo la referencia 0F8FAD5B-D9CB-469F-A165-70867728950E ya ha sido registrado bajo el UUID CCCCDDDD-1111-2222-3333-444455556666"})
+
+    def test_non_numeric_code_is_an_api_error(self):
+        with self.assertRaises(DigifactApiError):
+            self.certify_answering({"code": "Otro", "description": "?"})
+
+
+class TestTokenRenewalUnit(unittest.TestCase):
+    def test_expired_token_logs_in_again_and_retries_once(self):
+        session = (
+            FakeSession()
+            .on("post", "/v2/transform/nuc_json", response(401, {}), response(200, CERTIFIED))
+            .on("post", "/login/get_token", response(200, {"Token": "token-nuevo"}))
+        )
+        client = a_client(session, token="token-vencido")
+
+        result = client.invoice("CF", ITEMS)
+
+        certify_calls = session.calls_to("post", "/v2/transform/nuc_json")
+        self.assertEqual(result.auth_number, CERTIFIED["authNumber"])
+        self.assertEqual([call["headers"]["Authorization"] for call in certify_calls], ["token-vencido", "token-nuevo"])
+        self.assertEqual(client.token, "token-nuevo")
+
+    def test_token_only_client_reports_the_expired_token(self):
+        session = FakeSession().on("get", "/Shared", response(401, {}))
+        client = a_client(session, password="", token="token-vencido")
+
+        with self.assertRaises(DigifactAuthError):
+            client.get_dte_info("CCCCDDDD-1111-2222-3333-444455556666")
+        self.assertEqual(session.calls_to("post", "/login/get_token"), [])
+
+    def test_still_unauthorized_after_login_is_an_auth_error(self):
+        session = (
+            FakeSession()
+            .on("post", "/v2/transform/nuc_json", response(401, {}))
+            .on("post", "/login/get_token", response(200, {"Token": "token-nuevo"}))
+        )
+
+        with self.assertRaises(DigifactAuthError):
+            a_client(session).invoice("CF", ITEMS)
+        self.assertEqual(len(session.calls_to("post", "/v2/transform/nuc_json")), 2)
+
+
+class TestErrorClassificationUnit(unittest.TestCase):
+    def certify_with_status(self, status: int) -> DigifactApiError:
+        session = FakeSession().on("post", "/v2/transform/nuc_json", response(status, {"message": "error"}))
+        with self.assertRaises(DigifactApiError) as raised:
+            a_client(session).invoice("CF", ITEMS)
+        return raised.exception
+
+    def test_server_errors_are_retryable(self):
+        error = self.certify_with_status(503)
+
+        self.assertTrue(error.retryable)
+        self.assertEqual(error.code, 503)
+
+    def test_invalid_documents_are_not_retryable(self):
+        for status in (400, 406, 415):
+            with self.subTest(status=status):
+                self.assertFalse(self.certify_with_status(status).retryable)
+
+
+class TestFindByInternalReferenceUnit(unittest.TestCase):
+    def test_queries_shared_by_internal_reference_and_day(self):
+        rows = [{"GUID": "CCCCDDDD-1111-2222-3333-444455556666", "SERIE": "CCCCDDDD", "NUMERO": "123"}]
+        session = FakeSession().on("get", "/Shared", response(200, {"RESPONSE": rows}))
+
+        found = a_client(session).find_by_internal_reference(REFERENCE, "2026-11-03")
+
+        params = session.calls_to("get", "/Shared")[-1]["params"]
+        self.assertEqual(found, rows)
+        self.assertEqual(params["DATA1"], "SHARED_GETDTEINFO_BY_INTERNALID")
+        self.assertEqual(params["DATA2"], f"REFERENCIA_INTERNA|{REFERENCE}|ISSUEDDATE|2026-11-03")
+
+    def test_no_dte_with_that_reference_is_an_empty_list(self):
+        session = FakeSession().on("get", "/Shared", response(200, {"Respuesta": 0, "RESPONSE": []}))
+
+        self.assertEqual(a_client(session).find_by_internal_reference(REFERENCE, "2026-11-03"), [])
+
+    def test_a_reply_that_is_not_json_never_looks_like_an_absent_dte(self):
+        session = FakeSession().on("get", "/Shared", response(200, "<html>Mantenimiento</html>"))
+
+        with self.assertRaises(DigifactApiError) as raised:
+            a_client(session).find_by_internal_reference(REFERENCE, "2026-11-03")
+        self.assertTrue(raised.exception.retryable)
+
+
+if __name__ == "__main__":
+    unittest.main()