ecuafact 1.0.0b1__py3-none-any.whl

ecuafact/__init__.py

@@ -0,0 +1,97 @@
+"""Cliente oficial del API publico Ecuafact (contrato v1)."""
+
+from .client import EcuafactClient
+from .contribuyente import EcuafactContribuyente
+from .errors import EcuafactApiException, EcuafactSdkException
+from .models import (
+    Admission,
+    ApiError,
+    BusquedaContribuyente,
+    CampoAdicional,
+    ClaveAccesoDecodificada,
+    Comprobante,
+    ComprobanteRequest,
+    Compensacion,
+    Contexto,
+    Contribuyente,
+    ContribuyenteConsulta,
+    Detalle,
+    Destinatario,
+    DestinoSustitutiva,
+    DocsSustento,
+    EmisionResultado,
+    EstadoTributario,
+    EstablecimientoConsulta,
+    EstablecimientosContribuyente,
+    Impuesto,
+    ImpuestoDocSustento,
+    InfoDocumento,
+    InfoSustitutivaGuia,
+    InfoTributaria,
+    ListadoRequest,
+    MaquinaFiscal,
+    Motivo,
+    Operation,
+    Pago,
+    PaginaComprobantes,
+    QuotaBucket,
+    RepresentanteLegalConsulta,
+    RetencionFacturaLinea,
+    RetencionLinea,
+    ReembolsoDetalle,
+    RubroTercero,
+    TipoNegociable,
+    ValidacionIdentificacion,
+)
+from .options import EcuafactClientOptions, ResolvedOptions, resolve_options
+from .webhooks import sign, verify
+
+__all__ = [
+    "EcuafactClient",
+    "EcuafactContribuyente",
+    "EcuafactApiException",
+    "EcuafactSdkException",
+    "EcuafactClientOptions",
+    "ResolvedOptions",
+    "resolve_options",
+    "sign",
+    "verify",
+    "Admission",
+    "ApiError",
+    "BusquedaContribuyente",
+    "CampoAdicional",
+    "ClaveAccesoDecodificada",
+    "Comprobante",
+    "ComprobanteRequest",
+    "Compensacion",
+    "Contexto",
+    "Contribuyente",
+    "ContribuyenteConsulta",
+    "Detalle",
+    "Destinatario",
+    "DestinoSustitutiva",
+    "DocsSustento",
+    "EmisionResultado",
+    "EstadoTributario",
+    "EstablecimientoConsulta",
+    "EstablecimientosContribuyente",
+    "Impuesto",
+    "ImpuestoDocSustento",
+    "InfoDocumento",
+    "InfoSustitutivaGuia",
+    "InfoTributaria",
+    "ListadoRequest",
+    "MaquinaFiscal",
+    "Motivo",
+    "Operation",
+    "Pago",
+    "PaginaComprobantes",
+    "QuotaBucket",
+    "RepresentanteLegalConsulta",
+    "RetencionFacturaLinea",
+    "RetencionLinea",
+    "ReembolsoDetalle",
+    "RubroTercero",
+    "TipoNegociable",
+    "ValidacionIdentificacion",
+]

ecuafact/client.py

@@ -0,0 +1,436 @@
+"""Cliente HTTP del API publico Ecuafact para una credencial de integracion."""
+
+from __future__ import annotations
+
+import datetime as _datetime
+import json
+import random
+import time
+import uuid
+from email.utils import parsedate_to_datetime
+from typing import TypeVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import TypeAdapter, ValidationError
+
+from .errors import EcuafactApiException, EcuafactSdkException
+from .models import (
+    Admission,
+    ApiError,
+    BusquedaContribuyente,
+    ClaveAccesoDecodificada,
+    ComprobanteRequest,
+    Contexto,
+    ContribuyenteConsulta,
+    EmisionResultado,
+    EstablecimientosContribuyente,
+    ListadoRequest,
+    Operation,
+    PaginaComprobantes,
+    QuotaBucket,
+    ValidacionIdentificacion,
+    ArchivoComprobante,
+    PerfilEmisor,
+    PerfilEmisorUpdate,
+    CorreoEnviado,
+    CatalogoItem,
+)
+from .options import EcuafactClientOptions, ResolvedOptions, resolve_options
+
+TRANSIENT_STATUS = {408, 425, 429, 500, 502, 503, 504}
+T = TypeVar("T")
+
+
+class EcuafactClient:
+    """Cliente del API publico Ecuafact para una credencial de integracion."""
+
+    def __init__(self, options: EcuafactClientOptions) -> None:
+        self.options: ResolvedOptions = resolve_options(options)
+        self._http = httpx.Client(
+            base_url=self.options.base_address,
+            timeout=self.options.timeout,
+            headers={
+                "X-Api-Key": self.options.api_key,
+                "Accept": "application/json",
+                "User-Agent": self.options.user_agent,
+            },
+            transport=self.options.transport,
+        )
+
+    # -- ciclo de vida ------------------------------------------------------
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "EcuafactClient":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # -- API ----------------------------------------------------------------
+
+    def para(self, identificacion: str) -> "EcuafactContribuyente":
+        from .contribuyente import EcuafactContribuyente
+
+        return EcuafactContribuyente(self, identificacion)
+
+    def emitir(
+        self, comprobante: ComprobanteRequest, idempotency_key: str | None = None
+    ) -> EmisionResultado:
+        return self.emitir_en(self._require_identificacion(), comprobante, idempotency_key)
+
+    def emitir_en(
+        self,
+        identificacion: str,
+        comprobante: ComprobanteRequest,
+        idempotency_key: str | None = None,
+    ) -> EmisionResultado:
+        key = idempotency_key if idempotency_key else uuid.uuid4().hex
+        _validate_idempotency_key(key)
+        path = f"v1/contribuyentes/{_q(identificacion)}/comprobantes"
+        admission, correlation = self._send_meta("POST", path, comprobante, key, True, Admission)
+        return EmisionResultado(admission, key, correlation)
+
+    def get_operacion(self, id_operacion: str) -> Operation:
+        return self._send("GET", f"v1/operaciones/{id_operacion}", None, None, False, Operation)
+
+    def consultar_operacion(self, id_operacion: str) -> Operation:
+        """Igual que get_operacion. El API no expone un POST de consulta."""
+        return self.get_operacion(id_operacion)
+
+    def get_contexto(self) -> Contexto:
+        return self._send("GET", "v1/contexto", None, None, False, Contexto)
+
+    def descargar_ride(self, identificacion: str, clave_acceso: str) -> "ArchivoComprobante":
+        """Descarga el RIDE (PDF) de un comprobante emitido."""
+        return self._descargar(identificacion, clave_acceso, "ride")
+
+    def descargar_xml(self, identificacion: str, clave_acceso: str) -> "ArchivoComprobante":
+        """Descarga el XML. Revise provisional."""
+        return self._descargar(identificacion, clave_acceso, "xml")
+
+    def get_perfil(self, identificacion: str) -> "PerfilEmisor":
+        """Lee el perfil del emisor."""
+        return self._send("GET", self._ruta_perfil(identificacion), None, None, False, PerfilEmisor)
+
+    def enviar_correo(self, identificacion: str, clave_acceso: str, destinatario: str) -> CorreoEnviado:
+        """Reenvia el correo de un comprobante autorizado."""
+        path = f"v1/contribuyentes/{_q(identificacion)}/comprobantes/{_q(clave_acceso)}/correo"
+        response = self._http.request("POST", path, json={"destinatario": destinatario})
+        if response.status_code >= 400:
+            raise _build_api_exception(response.status_code, response.text, None, None)
+        datos = response.json().get("datos")
+        return CorreoEnviado.model_validate(datos)
+
+    def listar_catalogo(self, nombre: str) -> list[CatalogoItem]:
+        """Lee un catalogo publicado."""
+        return self._send("GET", f"v1/catalogos/{_q(nombre)}", None, None, False, CatalogoItem, list_result=True)
+
+    def actualizar_perfil(self, identificacion: str, cambios: PerfilEmisorUpdate) -> PerfilEmisor:
+        """Actualiza los campos editables del perfil."""
+        response = self._http.request(
+            "PUT",
+            self._ruta_perfil(identificacion),
+            json=cambios.model_dump(by_alias=True, exclude_none=True),
+        )
+        if response.status_code >= 400:
+            raise _build_api_exception(response.status_code, response.text, None, None)
+        datos = response.json().get("datos")
+        return PerfilEmisor.model_validate(datos)
+
+    def _ruta_perfil(self, identificacion: str) -> str:
+        return f"v1/contribuyentes/{_q(identificacion)}/perfil"
+
+    def _descargar(self, identificacion: str, clave_acceso: str, formato: str) -> ArchivoComprobante:
+        path = (
+            f"v1/contribuyentes/{_q(identificacion)}"
+            f"/comprobantes/{_q(clave_acceso)}/{formato}"
+        )
+        max_attempts = max(1, self.options.max_attempts) if self.options.retry_transient_failures else 1
+        response = None
+        for attempt in range(1, max_attempts + 1):
+            try:
+                response = self._http.request("GET", path)
+            except httpx.HTTPError as exc:
+                if attempt < max_attempts:
+                    _delay(self._compute_delay_ms(attempt, None))
+                    continue
+                raise EcuafactSdkException("No hay conexion con el API.") from exc
+            if (
+                response.status_code >= 400
+                and response.status_code in TRANSIENT_STATUS
+                and attempt < max_attempts
+            ):
+                _delay(self._compute_delay_ms(attempt, response.headers.get("Retry-After")))
+                continue
+            break
+        if response is None:
+            raise EcuafactSdkException("No fue posible completar la solicitud con el API.")
+        if response.status_code >= 400:
+            raise _build_api_exception(
+                response.status_code,
+                response.text,
+                response.headers.get("X-Correlation-Id"),
+                None,
+            )
+        tipo = response.headers.get("Content-Type", "application/octet-stream").split(";")[0]
+        marca = response.headers.get("X-Contenido", "")
+        return ArchivoComprobante(response.content, tipo, marca.lower() == "provisional")
+
+    def get_consumo(self) -> QuotaBucket:
+        return self._send("GET", "v1/consumo", None, None, True, QuotaBucket)
+
+    def listar_emitidos(self, filtros: ListadoRequest | None = None) -> PaginaComprobantes:
+        return self._listar(self._require_identificacion(), False, filtros)
+
+    def listar_recibidos(self, filtros: ListadoRequest | None = None) -> PaginaComprobantes:
+        return self._listar(self._require_identificacion(), True, filtros)
+
+    def listar_emitidos_en(
+        self, identificacion: str, filtros: ListadoRequest | None = None
+    ) -> PaginaComprobantes:
+        return self._listar(identificacion, False, filtros)
+
+    def listar_recibidos_en(
+        self, identificacion: str, filtros: ListadoRequest | None = None
+    ) -> PaginaComprobantes:
+        return self._listar(identificacion, True, filtros)
+
+    def consultar_contribuyente(
+        self, identificacion: str, fusionar: bool = True, fuente: str | None = None
+    ) -> ContribuyenteConsulta:
+        if not identificacion or not identificacion.strip():
+            raise EcuafactSdkException("La identificacion es obligatoria.")
+        flag = "true" if fusionar else "false"
+        path = f"v1/consultas/contribuyentes/{_q(identificacion)}?fusionar={flag}"
+        if fuente and fuente.strip():
+            path += f"&fuente={_q(fuente)}"
+        return self._send("GET", path, None, None, True, ContribuyenteConsulta)
+
+    def buscar_contribuyentes(
+        self,
+        apellidos: str,
+        nombres: str | None = None,
+        clase: str | None = None,
+        max: int | None = None,
+    ) -> list[BusquedaContribuyente]:
+        if not apellidos or not apellidos.strip():
+            raise EcuafactSdkException("apellidos es obligatorio.")
+        parts = [f"apellidos={_q(apellidos)}"]
+        if nombres and nombres.strip():
+            parts.append(f"nombres={_q(nombres)}")
+        if clase and clase.strip():
+            parts.append(f"clase={_q(clase)}")
+        if max is not None:
+            parts.append(f"max={max}")
+        path = "v1/consultas/contribuyentes?" + "&".join(parts)
+        return self._send_list("GET", path, BusquedaContribuyente)
+
+    def listar_establecimientos(self, ruc: str, filtro: str | None = None) -> EstablecimientosContribuyente:
+        if not ruc or not ruc.strip():
+            raise EcuafactSdkException("El RUC es obligatorio.")
+        path = f"v1/consultas/establecimientos/{_q(ruc)}"
+        if filtro and filtro.strip():
+            path += f"?filtro={_q(filtro)}"
+        return self._send("GET", path, None, None, True, EstablecimientosContribuyente)
+
+    def validar_identificacion(self, numero: str) -> ValidacionIdentificacion:
+        if not numero or not numero.strip():
+            raise EcuafactSdkException("El numero a validar es obligatorio.")
+        path = f"v1/consultas/identificacion/validar/{_q(numero)}"
+        return self._send("GET", path, None, None, True, ValidacionIdentificacion)
+
+    def decodificar_clave_acceso(self, clave_acceso: str) -> ClaveAccesoDecodificada:
+        if not clave_acceso or not clave_acceso.strip():
+            raise EcuafactSdkException("La clave de acceso es obligatoria.")
+        path = f"v1/consultas/comprobantes/decodificar/{_q(clave_acceso)}"
+        return self._send("GET", path, None, None, True, ClaveAccesoDecodificada)
+
+    # -- interno ------------------------------------------------------------
+
+    def _listar(
+        self,
+        identificacion: str,
+        recibidos: bool,
+        filtros: ListadoRequest | None,
+    ) -> PaginaComprobantes:
+        direccion = "recibidos" if recibidos else "emitidos"
+        path = (
+            f"v1/contribuyentes/{_q(identificacion)}"
+            f"/comprobantes/{direccion}{_build_query(filtros)}"
+        )
+        return self._send("GET", path, None, None, False, PaginaComprobantes)
+
+    def _send_list(self, method: str, path: str, model: type[T]) -> list[T]:
+        return self._send(method, path, None, None, True, model, list_result=True)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        body: ComprobanteRequest | None,
+        idempotency_key: str | None,
+        flat: bool,
+        model: type[T],
+        list_result: bool = False,
+    ) -> T:
+        data, _ = self._send_meta(method, path, body, idempotency_key, flat, model, list_result)
+        return data
+
+    def _send_meta(
+        self,
+        method: str,
+        path: str,
+        body: ComprobanteRequest | None,
+        idempotency_key: str | None,
+        flat: bool,
+        model: type[T],
+        list_result: bool = False,
+    ) -> tuple[T, str | None]:
+        # Solo se reintentan solicitudes idempotentes: GET, o POST/PUT con Idempotency-Key.
+        retryable = method == "GET" or (
+            idempotency_key is not None and method in ("POST", "PUT")
+        )
+        max_attempts = (
+            max(1, self.options.max_attempts)
+            if self.options.retry_transient_failures and retryable
+            else 1
+        )
+        headers: dict[str, str] = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        payload = body.model_dump(by_alias=True, exclude_none=True) if body is not None else None
+
+        for attempt in range(1, max_attempts + 1):
+            try:
+                response = self._http.request(method, path, json=payload, headers=headers)
+            except httpx.HTTPError as exc:
+                if attempt < max_attempts:
+                    _delay(self._compute_delay_ms(attempt, None))
+                    continue
+                raise EcuafactSdkException(
+                    "No hay conexion con el API. Si estaba emitiendo, conserve la misma Idempotency-Key y reintente."
+                ) from exc
+
+            correlation = response.headers.get("X-Correlation-Id")
+            if response.status_code >= 400:
+                if response.status_code in TRANSIENT_STATUS and attempt < max_attempts:
+                    _delay(self._compute_delay_ms(attempt, response.headers.get("Retry-After")))
+                    continue
+                raise _build_api_exception(response.status_code, response.text, correlation, idempotency_key)
+
+            return _parse(response.text, flat, model, list_result), correlation
+
+        raise EcuafactSdkException("No fue posible completar la solicitud con el API.")
+
+    def _compute_delay_ms(self, attempt: int, retry_after: str | None) -> float:
+        millis = (200.0 * attempt) + random.uniform(0, 50.0 * attempt)
+        if retry_after and self.options.respect_retry_after:
+            value = _parse_retry_after_ms(retry_after)
+            if value is not None and value > millis:
+                millis = value
+        cap = self.options.max_retry_delay_ms
+        if cap and cap > 0 and millis > cap:
+            millis = cap
+        return millis
+
+    def _require_identificacion(self) -> str:
+        value = self.options.identificacion
+        if not value or not value.strip():
+            raise EcuafactSdkException(
+                "Falta el RUC por defecto (identificacion). Configurelo para integraciones de un solo RUC o use "
+                "emitir_en(ruc, ...) o client.para(ruc)."
+            )
+        return value
+
+
+def _q(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _build_query(filtros: ListadoRequest | None) -> str:
+    if filtros is None:
+        return ""
+    parts: list[str] = []
+    for name, value in (
+        ("desde", filtros.desde),
+        ("hasta", filtros.hasta),
+        ("codDoc", filtros.cod_doc),
+        ("buscar", filtros.buscar),
+        ("pagina", filtros.pagina),
+        ("tamanoPagina", filtros.tamano_pagina),
+    ):
+        if value is None or value == "":
+            continue
+        parts.append(f"{name}={_q(str(value))}")
+    return "?" + "&".join(parts) if parts else ""
+
+
+def _parse(text: str, flat: bool, model: type[T], list_result: bool = False) -> T:
+    if text is None or text == "":
+        raise EcuafactSdkException("El API no devolvio datos.")
+    try:
+        data = json.loads(text)
+    except ValueError as exc:
+        raise EcuafactSdkException("Respuesta del API no reconocida.") from exc
+    if not flat:
+        data = data.get("datos") if isinstance(data, dict) else None
+        if data is None:
+            raise EcuafactSdkException("El API no devolvio datos.")
+    try:
+        if list_result:
+            return TypeAdapter(list[model]).validate_python(data)
+        return model.model_validate(data)
+    except ValidationError as exc:
+        raise EcuafactSdkException("Respuesta del API no reconocida.") from exc
+
+
+def _build_api_exception(
+    status: int, text: str, correlation: str | None, idempotency_key: str | None
+) -> EcuafactApiException:
+    error: ApiError | None = None
+    if text and text.strip():
+        try:
+            error = ApiError.model_validate_json(text)
+        except ValidationError:
+            error = None
+    return EcuafactApiException(
+        error.codigo if error else None,
+        error.mensaje if error else None,
+        status,
+        correlation,
+        (error.errores or []) if error else [],
+        idempotency_key,
+    )
+
+
+def _validate_idempotency_key(key: str) -> None:
+    if len(key) > 128:
+        raise EcuafactSdkException("Idempotency-Key no puede exceder 128 caracteres.")
+    if any(ord(character) > 127 for character in key):
+        raise EcuafactSdkException("Idempotency-Key debe ser ASCII.")
+
+
+def _delay(millis: float) -> None:
+    if millis > 0:
+        time.sleep(millis / 1000.0)
+
+
+def _parse_retry_after_ms(value: str) -> float | None:
+    text = value.strip()
+    if not text:
+        return None
+    if text.isdigit():
+        return float(text) * 1000.0
+    try:
+        when = parsedate_to_datetime(text)
+    except (TypeError, ValueError):
+        return None
+    if when is None:
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=_datetime.timezone.utc)
+    delta = (when - _datetime.datetime.now(_datetime.timezone.utc)).total_seconds() * 1000.0
+    return delta if delta > 0 else None

ecuafact/contribuyente.py

@@ -0,0 +1,31 @@
+"""Vista de emision y consulta fijada a un RUC (multi-RUC)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .errors import EcuafactSdkException
+from .models import EmisionResultado, ListadoRequest, PaginaComprobantes, QuotaBucket
+
+if TYPE_CHECKING:
+    from .client import EcuafactClient
+
+
+class EcuafactContribuyente:
+    def __init__(self, client: "EcuafactClient", identificacion: str) -> None:
+        if not identificacion or not identificacion.strip():
+            raise EcuafactSdkException("El RUC es obligatorio.")
+        self._client = client
+        self.identificacion = identificacion
+
+    def emitir(self, comprobante, idempotency_key: str | None = None) -> EmisionResultado:
+        return self._client.emitir_en(self.identificacion, comprobante, idempotency_key)
+
+    def listar_emitidos(self, filtros: ListadoRequest | None = None) -> PaginaComprobantes:
+        return self._client.listar_emitidos_en(self.identificacion, filtros)
+
+    def listar_recibidos(self, filtros: ListadoRequest | None = None) -> PaginaComprobantes:
+        return self._client.listar_recibidos_en(self.identificacion, filtros)
+
+    def get_consumo(self) -> QuotaBucket:
+        return self._client.get_consumo()

ecuafact/errors.py

@@ -0,0 +1,26 @@
+"""Error local del SDK (configuracion, transporte o respuesta no reconocida)."""
+
+
+class EcuafactSdkException(Exception):
+    """Error local del SDK."""
+
+
+class EcuafactApiException(EcuafactSdkException):
+    """Error devuelto por el API con el contrato publico (plano)."""
+
+    def __init__(
+        self,
+        codigo: str | None,
+        mensaje: str | None,
+        estado_http: int,
+        id_seguimiento: str | None,
+        errores: list[str],
+        idempotency_key: str | None,
+    ) -> None:
+        super().__init__(mensaje or f"El API devolvio el estado HTTP {estado_http}.")
+        self.codigo = codigo
+        self.mensaje = mensaje
+        self.estado_http = estado_http
+        self.id_seguimiento = id_seguimiento
+        self.errores = errores
+        self.idempotency_key = idempotency_key