bb_api 0.5.0__tar.gz → 0.5.1__tar.gz

{bb_api-0.5.0 → bb_api-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bb_api
-Version: 0.5.0
+Version: 0.5.1
 Summary: Wrapper da API do Banco do Brasil.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

{bb_api-0.5.0 → bb_api-0.5.1}/bb_api/__init__.py

@@ -4,11 +4,18 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("bb_api")
 except PackageNotFoundError:
-    __version__ = "0.5.0"
+    __version__ = "0.5.1"
 
 
 from .common import Ambiente
-from .accountability import AccountabilityV3RepasseAPI, AccountabilityV3ControleAPI
+from .accountability import (
+    MAX_DIAS_EXTRATO,
+    AccountabilityV3RepasseAPI,
+    AccountabilityV3ControleAPI,
+    ExtratoError,
+    IntervaloLongoDemaisError,
+    SemLancamentosError,
+)
 from .sia import (
     BBSiaAPI,
     CredenciaisNecessariasError,
@@ -21,11 +28,15 @@ from .gestao_agil import (
 )
 
 __all__ = [
+    "MAX_DIAS_EXTRATO",
     "Ambiente",
     "AccountabilityV3RepasseAPI",
     "AccountabilityV3ControleAPI",
     "BBSiaAPI",
     "CredenciaisNecessariasError",
+    "ExtratoError",
+    "IntervaloLongoDemaisError",
+    "SemLancamentosError",
     "FalhaDownload",
     "ResultadoDownloads",
     "parse_retorno_abertura_massificada",

{bb_api-0.5.0 → bb_api-0.5.1}/bb_api/accountability.py

@@ -9,6 +9,74 @@ import requests
 import bb_api.common as common
 
 
+MAX_DIAS_EXTRATO = 31
+"""Maior intervalo, em dias corridos, aceito numa consulta de extrato.
+
+``startDate`` e ``endDate`` podem distar no máximo esse tanto: 31 dias passam,
+32 devolvem ``400``. Períodos maiores precisam ser fatiados pelo chamador.
+"""
+
+_ERRO_SEM_LANCAMENTOS = "não existem lançamentos"
+_ERRO_INTERVALO_LONGO = "maior do que 31 dias"
+
+
+class ExtratoError(Exception):
+    """Erro devolvido pela API ao consultar o extrato do órgão repassador.
+
+    Carrega o status HTTP e a mensagem originais do Banco do Brasil, porque a
+    API usa ``400`` tanto para falha de verdade quanto para situações normais.
+    """
+
+    status_code: int
+    mensagem: str
+
+    def __init__(self, status_code: int, mensagem: str) -> None:
+        detalhe = f"(HTTP {status_code}): {mensagem}"
+        super().__init__(f"Não foi possível reaver o extrato do órgão repassador {detalhe}")
+        self.status_code = status_code
+        self.mensagem = mensagem
+
+
+class SemLancamentosError(ExtratoError):
+    """A conta não tem lançamento nenhum no período consultado.
+
+    A API responde ``400`` nesse caso, e não ``200`` com uma lista vazia, então
+    esse resultado normal chega como erro e precisa ser separado de uma falha —
+    senão uma conta parada vira indistinguível de uma consulta quebrada.
+    """
+
+
+class IntervaloLongoDemaisError(ExtratoError):
+    """O intervalo pedido passa dos ``MAX_DIAS_EXTRATO`` dias corridos."""
+
+
+def _mensagem_de_erro(res: requests.Response) -> str:
+    try:
+        corpo = cast("object", res.json())
+    except ValueError:
+        return res.text.strip()
+
+    if not isinstance(corpo, dict):
+        return res.text.strip()
+
+    campos = cast("dict[str, object]", corpo)
+    for chave in ("error", "message", "mensagem", "erro"):
+        valor = campos.get(chave)
+        if isinstance(valor, str) and valor:
+            return valor
+    return res.text.strip()
+
+
+def _erro_extrato(res: requests.Response) -> ExtratoError:
+    mensagem = _mensagem_de_erro(res)
+    normalizada = mensagem.casefold()
+    if _ERRO_SEM_LANCAMENTOS in normalizada:
+        return SemLancamentosError(res.status_code, mensagem)
+    if _ERRO_INTERVALO_LONGO in normalizada:
+        return IntervaloLongoDemaisError(res.status_code, mensagem)
+    return ExtratoError(res.status_code, mensagem)
+
+
 class _AccountabilityV3BaseAPI:
     _app_key: str
     _client_id: str
@@ -224,7 +292,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
+            raise _erro_extrato(res)
 
         res = common.parse_json_object(res)
 
@@ -1233,7 +1301,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
+            raise _erro_extrato(res)
 
         res = common.parse_json_object(res)
 

{bb_api-0.5.0 → bb_api-0.5.1}/bb_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bb_api
-Version: 0.5.0
+Version: 0.5.1
 Summary: Wrapper da API do Banco do Brasil.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

{bb_api-0.5.0 → bb_api-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bb_api"
-version = "0.5.0"
+version = "0.5.1"
 description = "Wrapper da API do Banco do Brasil."
 readme = "README.md"
 requires-python = ">=3.13"