bb_api 0.5.3__tar.gz → 0.5.5__tar.gz

{bb_api-0.5.3 → bb_api-0.5.5}/PKG-INFO

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

{bb_api-0.5.3 → bb_api-0.5.5}/bb_api/__init__.py

@@ -4,7 +4,7 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("bb_api")
 except PackageNotFoundError:
-    __version__ = "0.5.3"
+    __version__ = "0.5.5"
 
 
 from .common import Ambiente
@@ -14,6 +14,7 @@ from .accountability import (
     AccountabilityV3ControleAPI,
     ExtratoError,
     IntervaloLongoDemaisError,
+    RespostaError,
     SemLancamentosError,
 )
 from .sia import (
@@ -36,6 +37,7 @@ __all__ = [
     "CredenciaisNecessariasError",
     "ExtratoError",
     "IntervaloLongoDemaisError",
+    "RespostaError",
     "SemLancamentosError",
     "FalhaDownload",
     "ResultadoDownloads",

{bb_api-0.5.3 → bb_api-0.5.5}/bb_api/accountability.py

@@ -22,22 +22,73 @@ _ERRO_INTERVALO_LONGO = "maior do que 31 dias"
 _STATUS_SEM_MOVIMENTO = 404
 _SEM_MOVIMENTO_PADRAO = "não há movimento no período consultado"
 
+_LIMITE_DO_CORPO = 500
 
-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.
+class RespostaError(Exception):
+    """Resposta de erro devolvida pela API do Banco do Brasil.
+
+    Carrega o status HTTP e a mensagem originais junto da ação que falhou. Sem
+    eles, um ``404`` de "não há o que devolver", um ``403`` de escopo que falta
+    e um ``400`` de parâmetro inválido chegam ao chamador iguais.
+
+    Quando recebe a ``resposta``, guarda também o corpo cru e o
+    ``x-request-id``: o corpo traz o ``codigo`` e a ``ocorrencia`` do BB, que a
+    mensagem sozinha perde, e é com eles que o suporte do banco rastreia a falha.
     """
 
     status_code: int
     mensagem: str
+    corpo: str
+    request_id: str | None
 
-    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}")
+    def __init__(
+        self,
+        acao: str,
+        status_code: int,
+        mensagem: str,
+        *,
+        resposta: requests.Response | None = None,
+    ) -> None:
         self.status_code = status_code
         self.mensagem = mensagem
+        self.corpo = ""
+        self.request_id = None
+        if resposta is not None:
+            self.corpo = resposta.text.strip()
+            self.request_id = resposta.headers.get("x-request-id")
+        super().__init__(_descreve(acao, status_code, mensagem, self.corpo, self.request_id))
+
+
+def _descreve(
+    acao: str, status_code: int, mensagem: str, corpo: str, request_id: str | None
+) -> str:
+    partes = [f"Não foi possível {acao} (HTTP {status_code}): {mensagem}"]
+    if corpo and corpo != mensagem:
+        encurtado = corpo[:_LIMITE_DO_CORPO] + ("…" if len(corpo) > _LIMITE_DO_CORPO else "")
+        partes.append(f"resposta do BB: {encurtado}")
+    if request_id:
+        partes.append(f"x-request-id: {request_id}")
+    return " | ".join(partes)
+
+
+class ExtratoError(RespostaError):
+    """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.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        mensagem: str,
+        *,
+        resposta: requests.Response | None = None,
+    ) -> None:
+        super().__init__(
+            "reaver o extrato do órgão repassador", status_code, mensagem, resposta=resposta
+        )
 
 
 class SemLancamentosError(ExtratoError):
@@ -99,14 +150,19 @@ def _mensagem_da_lista_de_erros(campos: dict[str, object]) -> str:
     return ""
 
 
+def _erro(acao: str, res: requests.Response) -> RespostaError:
+    """Erro de uma resposta não-200, com a ação que falhou e o que o BB disse."""
+    return RespostaError(acao, res.status_code, _mensagem_de_erro(res), resposta=res)
+
+
 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)
+        return SemLancamentosError(res.status_code, mensagem, resposta=res)
     if _ERRO_INTERVALO_LONGO in normalizada:
-        return IntervaloLongoDemaisError(res.status_code, mensagem)
-    return ExtratoError(res.status_code, mensagem)
+        return IntervaloLongoDemaisError(res.status_code, mensagem, resposta=res)
+    return ExtratoError(res.status_code, mensagem, resposta=res)
 
 
 def _erro_extrato_aplicacao(res: requests.Response) -> ExtratoError:
@@ -118,7 +174,7 @@ def _erro_extrato_aplicacao(res: requests.Response) -> ExtratoError:
     """
     if res.status_code == _STATUS_SEM_MOVIMENTO:
         mensagem = _mensagem_de_erro(res) or _SEM_MOVIMENTO_PADRAO
-        return SemLancamentosError(res.status_code, mensagem)
+        return SemLancamentosError(res.status_code, mensagem, resposta=res)
     return _erro_extrato(res)
 
 
@@ -235,7 +291,7 @@ class _AccountabilityV3BaseAPI:
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível adquirir as novas credenciais de acesso.")
+            raise _erro("adquirir as novas credenciais de acesso", res)
 
         data = common.parse_json_object(res)
         self._access_token = cast("str", data["access_token"])
@@ -266,9 +322,7 @@ class _AccountabilityV3BaseAPI:
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar as agências próximas", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -411,7 +465,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("reaver o documento de despesa do programa de governo", res)
 
         res = common.parse_json_object(res)
 
@@ -542,7 +596,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("reaver o documento de despesa da prestação de contas", res)
 
         res = common.parse_json_object(res)
 
@@ -674,7 +728,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("reaver o extrato de subtransações do programa de governo", res)
 
         res = common.parse_json_object(res)
 
@@ -974,9 +1028,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar os lançamentos atualizados do programa de governo", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1017,9 +1069,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar os sublançamentos atualizados do programa de governo", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1053,9 +1103,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar as categorias do programa de governo", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1086,9 +1134,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("reaver o saldo das aplicações financeiras", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1125,9 +1171,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("reaver o saldo da conta corrente", res)
 
         res = common.parse_json_object(res)
 
@@ -1173,9 +1217,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code not in [200, 201]:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("categorizar a despesa do lançamento a crédito", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1222,9 +1264,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code not in [200, 201]:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("identificar o lançamento a crédito", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1255,9 +1295,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code not in [200, 201]:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("excluir a identificação do lançamento a crédito", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1286,9 +1324,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar as identificações dos lançamentos a débito", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1431,7 +1467,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("reaver o documento de despesa do programa de governo", res)
 
         res = common.parse_json_object(res)
 
@@ -1562,7 +1598,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("reaver o documento de despesa da prestação de contas", res)
 
         res = common.parse_json_object(res)
 
@@ -1688,9 +1724,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("reaver o extrato de subtransações do programa de governo", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1978,9 +2012,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar as contas correntes do órgão de controle", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(

{bb_api-0.5.3 → bb_api-0.5.5}/bb_api/common.py

@@ -60,9 +60,27 @@ def handle_numeric_string_with_symbols(v: str) -> str:
     return re.sub(r"\D", "", v)
 
 
+def _data_de_texto(texto: str) -> datetime:
+    """Interpreta uma data em ISO ou em dd/mm/aaaa.
+
+    A API devolve os dois formatos, e o valor de uma resposta costuma virar
+    parâmetro da consulta seguinte: o ``bookingDate`` do extrato chega em
+    dd/mm/aaaa e é o que identifica o documento de despesa daquela transação.
+    """
+    formatos = ("%Y-%m-%d", "%d/%m/%Y")
+    for formato in formatos:
+        try:
+            return datetime.strptime(texto, formato)
+        except ValueError:
+            continue
+
+    aceitos = " ou ".join(formatos)
+    raise ValueError(f"A data '{texto}' não está em {aceitos}.")
+
+
 def handle_dates(v: DateLike) -> str:
     if isinstance(v, str):
-        dt = datetime.strptime(v, "%Y-%m-%d")
+        dt = _data_de_texto(v)
     elif isinstance(v, datetime):
         dt = v
     else:

{bb_api-0.5.3 → bb_api-0.5.5}/bb_api.egg-info/PKG-INFO

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

{bb_api-0.5.3 → bb_api-0.5.5}/pyproject.toml

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