nodda-client 1.2.0__py3-none-any.whl

nodda_client/__init__.py

@@ -0,0 +1,18 @@
+"""SDK publico de Nodda -- capa 3. Cliente HTTP delgado, sin conocimiento
+de AEAT, certificados, ni logica de negocio.
+"""
+
+from .client import NoddaClient
+from .exceptions import NoddaApiException, NoddaException
+from .http_transport import HttpTransport, RespuestaHttp, UrllibHttpTransport
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "NoddaClient",
+    "NoddaException",
+    "NoddaApiException",
+    "HttpTransport",
+    "RespuestaHttp",
+    "UrllibHttpTransport",
+]

nodda_client/client.py

@@ -0,0 +1,229 @@
+"""Cliente del SDK publico de Nodda (capa 3)."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import secrets
+from urllib.parse import quote, urlencode
+
+from .exceptions import NoddaApiException, NoddaException
+from .http_transport import HttpTransport, RespuestaHttp, UrllibHttpTransport
+
+
+class NoddaClient:
+    """SDK publico de Nodda -- capa 3 de la arquitectura::
+
+        Este SDK -> API propia -> Core Engine -> AEAT
+
+    A proposito NO sabe nada de AEAT, certificados, XML, ni hash -- solo
+    habla HTTP/JSON con la API propia. Cualquier logica de negocio
+    (validaciones, reglas de VERI*FACTU) vive del lado de la API/Core
+    Engine, nunca aqui.
+
+    Multi-NIF: un token puede autorizar varios NIF ("1 cuenta principal,
+    varias empresas"). Por eso cada metodo que habla con una factura
+    especifica acepta un ``nif`` OPCIONAL -- si tu token solo tiene 1 NIF
+    autorizado, puedes seguir sin pasarlo.
+    """
+
+    def __init__(self, base_url: str, api_key: str, http: HttpTransport | None = None) -> None:
+        self._base_url = base_url
+        self._api_key = api_key
+        self._http: HttpTransport = http or UrllibHttpTransport()
+        self._ultimo_correlation_id: str | None = None
+        self._ultimo_cupo_restante: int | None = None
+
+    def crear_factura(self, datos: dict, nif: str | None = None) -> dict:
+        """POST /v1/invoices -- registra una factura. Siempre devuelve de
+        inmediato con status "queued"; usa consultar_estado() despues para
+        saber el resultado real.
+        """
+        if nif is not None:
+            datos = {**datos, "nif": nif}
+        return self._peticion("POST", "/v1/invoices", datos)
+
+    def consultar_estado(self, id: str, nif: str | None = None) -> dict:
+        """GET /v1/invoices/{id} -- estado real de una factura ya emitida."""
+        return self._peticion("GET", f"/v1/invoices/{id}{self._query_nif(nif)}")
+
+    def cancelar_factura(self, id: str, datos: dict | None = None, nif: str | None = None) -> dict:
+        """POST /v1/invoices/{id}/cancel -- anula una factura. VERI*FACTU no
+        permite borrar, solo anular con un registro nuevo.
+        """
+        datos = dict(datos or {})
+        if nif is not None:
+            datos["nif"] = nif
+        return self._peticion("POST", f"/v1/invoices/{id}/cancel", datos)
+
+    def obtener_url_qr(self, id: str, nif: str | None = None) -> str:
+        """GET /v1/invoices/{id}/qr?format=url -- la URL del codigo QR."""
+        query = f"?format=url&nif={quote(nif)}" if nif is not None else "?format=url"
+        respuesta = self._peticion("GET", f"/v1/invoices/{id}/qr{query}")
+        return str(respuesta["url"])
+
+    def obtener_imagen_qr(self, id: str, nif: str | None = None) -> bytes:
+        """GET /v1/invoices/{id}/qr -- la imagen PNG del codigo QR, en
+        binario crudo (bytes, listo para guardar a archivo o incrustar en
+        un PDF).
+        """
+        respuesta = self._http.request(
+            "GET",
+            self._url_completa(f"/v1/invoices/{id}/qr{self._query_nif(nif)}"),
+            self._headers(),
+        )
+        if respuesta.status >= 400:
+            self._lanzar_error_desde_json(respuesta)
+        return respuesta.body
+
+    def estado_sistema(self, nif: str | None = None) -> dict:
+        """GET /v1/status -- si se puede enviar ahora o hay que esperar
+        (control de flujo de AEAT). El tiempo de espera es por certificado,
+        no por token.
+        """
+        return self._peticion("GET", f"/v1/status{self._query_nif(nif)}")
+
+    def listar_facturas(self, filtros: dict | None = None, nif: str | None = None) -> dict:
+        """GET /v1/invoices -- lista las facturas propias, con filtros
+        opcionales (status, type, from, to, limit, offset).
+        """
+        filtros = dict(filtros or {})
+        if nif is not None:
+            filtros["nif"] = nif
+        query = f"?{urlencode(filtros)}" if filtros else ""
+        return self._peticion("GET", f"/v1/invoices{query}")
+
+    def reintentar_factura(self, id: str, tipo: str | None = None, nif: str | None = None) -> dict:
+        """POST /v1/invoices/{id}/retry -- fuerza un reintento manual, sin
+        esperar el ciclo automatico. ``tipo`` es 'alta' o 'anulacion'.
+        """
+        parametros: dict[str, str] = {}
+        if tipo is not None:
+            parametros["type"] = tipo
+        if nif is not None:
+            parametros["nif"] = nif
+        query = f"?{urlencode(parametros)}" if parametros else ""
+        return self._peticion("POST", f"/v1/invoices/{id}/retry{query}")
+
+    def obtener_perfil(self) -> dict:
+        """GET /v1/client -- los NIF autorizados para este token."""
+        return self._peticion("GET", "/v1/client")
+
+    def configurar_webhook(self, url: str, nif: str | None = None) -> dict:
+        """PUT /v1/webhooks -- configura la URL (https) a la que Nodda avisa cuando la AEAT responde.
+        La respuesta trae el ``secreto`` de firma UNA sola vez: guardalo para verificar_firma_webhook()."""
+        return self._peticion("PUT", f"/v1/webhooks{self._query_nif(nif)}", {"url": url})
+
+    def quitar_webhook(self, nif: str | None = None) -> dict:
+        """DELETE /v1/webhooks -- deja de enviar avisos."""
+        return self._peticion("DELETE", f"/v1/webhooks{self._query_nif(nif)}")
+
+    @staticmethod
+    def verificar_firma_webhook(cuerpo: bytes | str, firma: str | None, secreto: str) -> bool:
+        """Comprueba que un aviso viene de Nodda: X-Nodda-Signature es el HMAC-SHA256 (hex) del cuerpo EXACTO
+        recibido, con tu secreto. Usa el cuerpo sin decodificar."""
+        if not firma or not secreto:
+            return False
+        datos = cuerpo.encode("utf-8") if isinstance(cuerpo, str) else cuerpo
+        esperada = hmac.new(secreto.encode("utf-8"), datos, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(esperada, firma.strip().lower())
+
+    def ultimo_correlation_id(self) -> str | None:
+        """El X-Correlation-Id enviado en la ultima peticion, o None."""
+        return self._ultimo_correlation_id
+
+    def ultimo_cupo_restante(self) -> int | None:
+        """Cuantas facturas gratuitas le quedan al cliente segun el ultimo
+        crear_factura() -- None si el NIF no esta sujeto a cupo (plan de
+        pago) o si el servidor no mando el encabezado. No hace su propia
+        peticion -- solo lee el encabezado de la ULTIMA respuesta.
+        """
+        return self._ultimo_cupo_restante
+
+    @staticmethod
+    def registrar_cuenta(
+        base_url: str,
+        email: str,
+        nif: str,
+        nombre_emisor: str,
+        telefono: str | None = None,
+        http: HttpTransport | None = None,
+    ) -> dict:
+        """POST /v1/cuentas -- registro publico, SIN necesitar una API Key
+        previa (por eso es estatico y no manda Authorization). Devuelve una
+        API Key nueva -- guardala de inmediato, el servidor no la vuelve a
+        mostrar.
+        """
+        http = http or UrllibHttpTransport()
+        datos = {"email": email, "nif": nif, "nombreEmisor": nombre_emisor}
+        if telefono is not None:
+            datos["telefono"] = telefono
+
+        respuesta = http.request(
+            "POST",
+            f"{base_url.rstrip('/')}/v1/cuentas",
+            {"Content-Type": "application/json"},
+            json.dumps(datos),
+        )
+        if respuesta.status >= 400:
+            NoddaClient._lanzar_error_estatico(respuesta)
+        decodificado = NoddaClient._intentar_json(respuesta.body)
+        if decodificado is None:
+            raise NoddaException(
+                f"La API devolvio una respuesta que no es JSON valido: {respuesta.body.decode('utf-8', 'replace')}"
+            )
+        return decodificado
+
+    # -- internos -----------------------------------------------------------
+
+    @staticmethod
+    def _query_nif(nif: str | None) -> str:
+        return f"?nif={quote(nif)}" if nif is not None else ""
+
+    def _peticion(self, metodo: str, ruta: str, datos: dict | None = None) -> dict:
+        cuerpo = json.dumps(datos) if datos is not None else None
+        respuesta = self._http.request(metodo, self._url_completa(ruta), self._headers(), cuerpo)
+
+        if respuesta.status >= 400:
+            self._lanzar_error_desde_json(respuesta)
+
+        valor = respuesta.headers.get("X-Nodda-Quota-Remaining")
+        self._ultimo_cupo_restante = int(valor) if valor is not None else None
+
+        decodificado = self._intentar_json(respuesta.body)
+        if decodificado is None:
+            raise NoddaException(
+                f"La API devolvio una respuesta que no es JSON valido: {respuesta.body.decode('utf-8', 'replace')}"
+            )
+        return decodificado
+
+    def _lanzar_error_desde_json(self, respuesta: RespuestaHttp) -> None:
+        self._lanzar_error_estatico(respuesta)
+
+    @staticmethod
+    def _lanzar_error_estatico(respuesta: RespuestaHttp) -> None:
+        decodificado = NoddaClient._intentar_json(respuesta.body) or {}
+        error = decodificado.get("error", {}) if isinstance(decodificado, dict) else {}
+        mensaje = error.get("message") or f"La API respondio con el codigo HTTP {respuesta.status}."
+        codigo = error.get("code")
+        raise NoddaApiException(mensaje, respuesta.status, codigo)
+
+    def _url_completa(self, ruta: str) -> str:
+        return self._base_url.rstrip("/") + ruta
+
+    def _headers(self) -> dict[str, str]:
+        self._ultimo_correlation_id = secrets.token_hex(16)
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "X-Correlation-Id": self._ultimo_correlation_id,
+        }
+
+    @staticmethod
+    def _intentar_json(body: bytes):
+        try:
+            valor = json.loads(body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return None
+        return valor if isinstance(valor, (dict, list)) else None

nodda_client/exceptions.py

@@ -0,0 +1,26 @@
+"""Excepciones del SDK publico de Nodda."""
+
+from __future__ import annotations
+
+
+class NoddaException(Exception):
+    """Excepcion generica de comunicacion (red, timeout).
+
+    Para errores que la API devuelve con codigo HTTP de error (422, 404,
+    etc.), ver NoddaApiException -- son cosas distintas: esta es "no se
+    pudo ni hablar con la API", la otra es "la API respondio, pero con un
+    error".
+    """
+
+
+class NoddaApiException(NoddaException):
+    """Se lanza cuando la API de Nodda SI respondio, pero con un codigo de
+    error (422 = dato invalido o regla de negocio, 404 = no encontrado,
+    500 = error interno). Distinta de NoddaException (esa es cuando ni
+    siquiera hubo respuesta -- problema de red).
+    """
+
+    def __init__(self, mensaje: str, status_code: int, codigo_error: str | None) -> None:
+        super().__init__(mensaje)
+        self.status_code = status_code
+        self.codigo_error = codigo_error

nodda_client/http_transport.py

@@ -0,0 +1,91 @@
+"""Transporte HTTP del SDK: interfaz + implementacion real con urllib."""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from .exceptions import NoddaException
+
+
+@dataclass
+class RespuestaHttp:
+    """Respuesta cruda del transporte.
+
+    body son bytes (texto JSON o imagen PNG); headers tiene el nombre del
+    encabezado en Title-Case.
+    """
+
+    status: int
+    body: bytes
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+class HttpTransport(Protocol):
+    """Abstrae el transporte HTTP -- misma razon que HttpClientInterface en
+    el SDK de PHP: sin esto no se puede probar NoddaClient con un doble de
+    prueba en vez de la conexion real. La implementacion real es
+    UrllibHttpTransport.
+    """
+
+    def request(
+        self,
+        metodo: str,
+        url: str,
+        headers: dict[str, str] | None = None,
+        cuerpo: str | None = None,
+    ) -> RespuestaHttp:
+        ...
+
+
+class UrllibHttpTransport:
+    """Implementacion real usando urllib de la biblioteca estandar -- sin
+    requests ni ninguna otra libreria HTTP, mismo criterio que el SDK de
+    PHP (curl crudo, sin Guzzle): mantener el SDK publico con el minimo de
+    dependencias posible, ya que lo va a instalar gente externa.
+    """
+
+    _TIEMPO_LIMITE = 30
+
+    def request(
+        self,
+        metodo: str,
+        url: str,
+        headers: dict[str, str] | None = None,
+        cuerpo: str | None = None,
+    ) -> RespuestaHttp:
+        headers = headers or {}
+        datos = cuerpo.encode("utf-8") if cuerpo is not None else None
+        peticion = urllib.request.Request(url=url, data=datos, headers=headers, method=metodo.upper())
+
+        try:
+            with urllib.request.urlopen(peticion, timeout=self._TIEMPO_LIMITE) as respuesta:
+                return RespuestaHttp(
+                    status=respuesta.status,
+                    body=respuesta.read(),
+                    headers=self._normalizar(respuesta.headers.items()),
+                )
+        except urllib.error.HTTPError as e:
+            # La API respondio con un codigo de error (>= 400); no es un
+            # fallo de red -- se devuelve como respuesta normal para que
+            # NoddaClient lo traduzca a NoddaApiException.
+            return RespuestaHttp(
+                status=e.code,
+                body=e.read(),
+                headers=self._normalizar(e.headers.items() if e.headers else []),
+            )
+        except urllib.error.URLError as e:
+            raise NoddaException(f"Fallo de comunicacion con la API de Nodda: {e.reason}") from e
+
+    @staticmethod
+    def _normalizar(items) -> dict[str, str]:
+        # HTTP/2 manda los nombres en minusculas; se normalizan a Title-Case
+        # para que el resto del codigo pueda buscar por un nombre fijo
+        # (p. ej. "X-Nodda-Quota-Remaining").
+        encabezados: dict[str, str] = {}
+        for nombre, valor in items:
+            titulo = "-".join(p[:1].upper() + p[1:] for p in nombre.split("-"))
+            encabezados[titulo] = valor
+        return encabezados

nodda_client-1.2.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: nodda-client
+Version: 1.2.0
+Summary: Cliente oficial de la API de Nodda para emitir y consultar facturas VERI*FACTU (AEAT).
+Author-email: Nodda <soporte@nodda.es>
+License: MIT
+Project-URL: Documentacion, https://app.nodda.es/developers/introduccion
+Project-URL: Repositorio, https://gitlab.com/Bitfx/nodda-facturacion/nodda-cliente
+Keywords: verifactu,aeat,facturacion,factura,nodda
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nodda-client (Python)
+
+Cliente oficial de la API de [Nodda](https://nodda.es) para emitir y consultar facturas **VERI\*FACTU** de la Agencia Tributaria (AEAT) desde tu propio programa (ERP, tienda online, TPV…).
+
+Nodda se encarga de la firma con tu certificado, del XML, de la cadena de huellas y del envío a la AEAT: tú solo mandas los datos de la factura en JSON.
+
+## Instalación
+
+```bash
+pip install nodda-client
+```
+
+Requisitos: Python 3.8 o superior. Sin dependencias (solo la librería estándar).
+
+## Antes de empezar
+
+1. Crea tu cuenta en el portal de Nodda y da de alta tu empresa (NIF y certificado digital).
+2. Genera tu **clave API** en el portal → *API keys*.
+3. Usa la dirección del entorno con su clave:
+
+| Entorno | Dirección | Uso |
+|---|---|---|
+| Pruebas | `https://sandbox.nodda.es` | Envía al entorno de pruebas de la AEAT, sin validez fiscal |
+| Producción | `https://api.nodda.es` | Facturas reales |
+
+La clave de pruebas no sirve en producción, ni al revés.
+
+## Uso
+
+```python
+import os
+from nodda_client import NoddaClient
+
+nodda = NoddaClient("https://sandbox.nodda.es", os.environ["NODDA_API_KEY"])
+
+r = nodda.crear_factura({
+    "series": "2026", "issueDate": "2026-11-03", "invoiceType": "F1",
+    "description": "Servicios de consultoría", "taxRegimeKey": "01", "operationQualification": "S1",
+    "taxBase": "100.00", "taxRate": "21", "taxAmount": "21.00", "totalAmount": "121.00",
+    "recipients": [{"nif": "B12345674", "name": "Cliente Demo SL"}],
+})
+# r["status"] == "queued": la API responde al momento; la AEAT, unos segundos después.
+
+estado = nodda.consultar_estado(r["id"])  # queued, sent, accepted_with_errors o permanently_failed
+```
+
+Si tu clave da acceso a varias empresas (NIF), indica cuál en el parámetro `nif` de cada método. Puedes asociar la factura a un centro de coste enviando `costCenterId` en los datos.
+
+## Métodos
+
+| Método | Endpoint |
+|---|---|
+| `crear_factura(datos, nif=None)` | `POST /v1/invoices` |
+| `consultar_estado(id, nif=None)` | `GET /v1/invoices/{id}` |
+| `listar_facturas(filtros=None, nif=None)` | `GET /v1/invoices` |
+| `cancelar_factura(id, datos=None, nif=None)` | `POST /v1/invoices/{id}/cancel` |
+| `reintentar_factura(id, tipo=None, nif=None)` | `POST /v1/invoices/{id}/retry` |
+| `obtener_url_qr(id)` / `obtener_imagen_qr(id)` | `GET /v1/invoices/{id}/qr` |
+| `estado_sistema(nif=None)` | `GET /v1/status` |
+| `obtener_perfil()` | `GET /v1/client` |
+| `configurar_webhook(url, nif=None)` / `quitar_webhook(nif=None)` | `PUT` / `DELETE /v1/webhooks` |
+| `NoddaClient.verificar_firma_webhook(cuerpo, firma, secreto)` | Comprueba la firma de un aviso |
+
+## Avisos (webhooks)
+
+En lugar de consultar el estado de cada factura, Nodda puede avisar a tu servidor cuando la AEAT responde. Configura la URL con `configurar_webhook(url)` (la respuesta trae el `secreto` **una sola vez**: guárdalo) y, en tu endpoint, comprueba la firma antes de confiar en el aviso:
+
+```python
+# cuerpo: bytes tal cual llegan; firma: cabecera X-Nodda-Signature
+if not NoddaClient.verificar_firma_webhook(cuerpo, firma, os.environ["NODDA_WEBHOOK_SECRET"]):
+    return 401
+```
+
+El cuerpo trae `id` (número de factura), `status` (`sent`, `accepted_with_errors` o `permanently_failed`), `razon`, `eventId` y los datos del acuse de la AEAT. Responde con un código 2xx; si no, Nodda lo reintenta.
+
+## Errores
+
+Si la API responde con un error, se lanza `NoddaApiException` con el código HTTP y un código estable (por ejemplo `invalid_request`, `business_rule_violation`, `certificate_not_configured`). Si no hubo respuesta (fallo de red), se lanza `NoddaException`: puedes reintentar la misma petición.
+
+## Documentación
+
+Guía completa, campos de cada petición y códigos de error: <https://app.nodda.es/developers/introduccion>
+Referencia OpenAPI: <https://api.nodda.es/openapi.json>
+
+Soporte: soporte@nodda.es
+
+## Licencia
+
+MIT

nodda_client-1.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+nodda_client/__init__.py,sha256=3O7vFVbl0WnaDhGCRihnyrQHu4WmMXrMS7x_aiCdYvE,465
+nodda_client/client.py,sha256=oIKOlnrvGz6J1_KPHIBpNm2AGSqpUDP_mRZ08rGAiE4,9921
+nodda_client/exceptions.py,sha256=AYPHee0S7J4GxewttY4w_rafJpIQ1SuuEPR_ix7zF1o,936
+nodda_client/http_transport.py,sha256=rqBNd-HfTi9A0n15xDrwc97JMJLHAJrZWcrs6h7GDAM,3131
+nodda_client-1.2.0.dist-info/licenses/LICENSE,sha256=GCyPSNhLNR3iRMKRRjXPqnwbYYjkPOCapSBJYmc2-ec,1062
+nodda_client-1.2.0.dist-info/METADATA,sha256=hbe-_5a6GgznOAtP05bYKlmXvPZkyQl3FRndfcNkXTE,4573
+nodda_client-1.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+nodda_client-1.2.0.dist-info/top_level.txt,sha256=TvZgJaGt4UkVGHMBjXLEx7CfH33b870Ww8QPQkZWfow,13
+nodda_client-1.2.0.dist-info/RECORD,,

nodda_client-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nodda_client-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nodda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodda_client-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nodda_client