bb_api 0.5.0__tar.gz → 0.5.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bb_api
-Version: 0.5.0
+Version: 0.5.2
 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.2}/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.2"
 
 
 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.2}/bb_api/accountability.py

@@ -9,6 +9,119 @@ 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"
+
+_STATUS_SEM_MOVIMENTO = 404
+_SEM_MOVIMENTO_PADRAO = "não há movimento no período consultado"
+
+
+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.
+
+    Nos extratos de aplicação (fundos de investimento e poupança) a mesma
+    situação chega como ``404`` de corpo vazio, e cobre tanto o mês sem
+    movimento quanto a aplicação que a conta não possui.
+    """
+
+
+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
+
+    detalhada = _mensagem_da_lista_de_erros(campos)
+    if detalhada:
+        return detalhada
+    return res.text.strip()
+
+
+def _mensagem_da_lista_de_erros(campos: dict[str, object]) -> str:
+    """Extrai a mensagem de um corpo no formato ``{"erros": [{...}]}``.
+
+    ``menssagem``, com dois esses, é como o Banco do Brasil escreve a chave
+    nesse formato de erro.
+    """
+    for chave in ("erros", "errors"):
+        itens = campos.get(chave)
+        if not isinstance(itens, list) or not itens:
+            continue
+        primeiro = cast("list[object]", itens)[0]
+        if not isinstance(primeiro, dict):
+            continue
+        item = cast("dict[str, object]", primeiro)
+        for interna in ("menssagem", "mensagem", "message", "descricao"):
+            valor = item.get(interna)
+            if isinstance(valor, str) and valor:
+                return valor
+    return ""
+
+
+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)
+
+
+def _erro_extrato_aplicacao(res: requests.Response) -> ExtratoError:
+    """Classifica o erro dos extratos de fundo de investimento e de poupança.
+
+    Esses extratos usam ``404`` de corpo vazio para "não há o que devolver" —
+    mês sem movimento ou aplicação que a conta não tem —, então esse status
+    vira :class:`SemLancamentosError` em vez de falha.
+    """
+    if res.status_code == _STATUS_SEM_MOVIMENTO:
+        mensagem = _mensagem_de_erro(res) or _SEM_MOVIMENTO_PADRAO
+        return SemLancamentosError(res.status_code, mensagem)
+    return _erro_extrato(res)
+
+
 class _AccountabilityV3BaseAPI:
     _app_key: str
     _client_id: str
@@ -224,7 +337,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)
 
@@ -617,6 +730,15 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         mes: int,
         ano: int,
     ) -> pd.DataFrame:
+        """Reaver o extrato mensal de um fundo de investimento da conta.
+
+        ``fundo_investimento_id`` é o ``grupoAtivo`` que
+        :meth:`get_saldo_aplicacoes_financeiras` devolve em cada operação — não
+        o ``codigo`` nem a ``modalidade``, que respondem ``404``.
+
+        Levanta :class:`SemLancamentosError` quando o mês não tem movimento ou
+        a conta não tem esse fundo.
+        """
         access_token = self._get_access_token()
 
         res = requests.request(
@@ -631,9 +753,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_extrato_aplicacao(res)
 
         res = common.parse_json_object(res)
         extrato = cast("dict[str, object]", res["extrato"])
@@ -643,7 +763,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
             main_list="listaLancamentosExtrato",
             insertables=[
                 "numeroAgenciaRecebedora",
-                "digitoVerificadorContaRecebedora",
+                "digitoVerificadoraContaRecebedora",
                 "numeroContaCorrenteRecebedora",
                 "numeroDigitoVerificadorContaCorrenteRecebedora",
                 "nomeClienteRecebedor",
@@ -651,7 +771,6 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
                 "CNPJFundoInvestimento",
                 "valorCotaExtrato",
                 "dataAfericaoValorCota",
-                "ultimaCotacaoCota",
                 "dataUltimaCotacaoCota",
                 "sinalRentabilidadeMes",
                 "valorRentabilidadeMes",
@@ -690,7 +809,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
             ],
             rename_dict={
                 "numeroAgenciaRecebedora": "Número Agência Recebedora",
-                "digitoVerificadorContaRecebedora": "Dígito Verificador Conta Recebedora",
+                "digitoVerificadoraContaRecebedora": "Dígito Verificador Conta Recebedora",
                 "numeroContaCorrenteRecebedora": "Número Conta Corrente Recebedora",
                 "numeroDigitoVerificadorContaCorrenteRecebedora": "Número Dígito Verificador Conta Corrente Recebedora",
                 "nomeClienteRecebedor": "Nome Cliente Recebedor",
@@ -698,7 +817,6 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
                 "CNPJFundoInvestimento": " CNPJ Fundo Investimento",
                 "valorCotaExtrato": "Valor Cota Extrato",
                 "dataAfericaoValorCota": "Data Afericão Valor Cota",
-                "ultimaCotacaoCota": "Última Cotação Cota",
                 "dataUltimaCotacaoCota": "Data Última Cotação Cota",
                 "sinalRentabilidadeMes": "Sinal Rentabilidade Mês",
                 "valorRentabilidadeMes": "Valor Rentabilidade Mês",
@@ -769,6 +887,12 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         mes: int,
         ano: int,
     ) -> pd.DataFrame:
+        """Reaver o extrato mensal de uma variação de poupança da conta.
+
+        Levanta :class:`SemLancamentosError` quando não há o que devolver e
+        :class:`ExtratoError` quando a variação não existe — nesse caso a API
+        responde ``400`` dizendo que o número da variação não é válido.
+        """
         access_token = self._get_access_token()
 
         res = requests.request(
@@ -783,9 +907,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_extrato_aplicacao(res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1233,7 +1355,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)
 
@@ -1621,6 +1743,14 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         mes: int,
         ano: int,
     ) -> pd.DataFrame:
+        """Reaver o extrato mensal de um fundo de investimento da conta.
+
+        ``fundo_investimento_id`` é o ``grupoAtivo`` da operação no saldo de
+        aplicações financeiras, não o ``codigo`` nem a ``modalidade``.
+
+        Levanta :class:`SemLancamentosError` quando o mês não tem movimento ou
+        a conta não tem esse fundo.
+        """
         access_token = self._get_access_token()
 
         res = requests.request(
@@ -1635,9 +1765,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_extrato_aplicacao(res)
 
         res = common.parse_json_object(res)
         extrato = cast("dict[str, object]", res["extrato"])
@@ -1647,7 +1775,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
             main_list="listaLancamentosExtrato",
             insertables=[
                 "numeroAgenciaRecebedora",
-                "digitoVerificadorContaRecebedora",
+                "digitoVerificadoraContaRecebedora",
                 "numeroContaCorrenteRecebedora",
                 "numeroDigitoVerificadorContaCorrenteRecebedora",
                 "nomeClienteRecebedor",
@@ -1655,7 +1783,6 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
                 "CNPJFundoInvestimento",
                 "valorCotaExtrato",
                 "dataAfericaoValorCota",
-                "ultimaCotacaoCota",
                 "dataUltimaCotacaoCota",
                 "sinalRentabilidadeMes",
                 "valorRentabilidadeMes",
@@ -1694,7 +1821,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
             ],
             rename_dict={
                 "numeroAgenciaRecebedora": "Número Agência Recebedora",
-                "digitoVerificadorContaRecebedora": "Dígito Verificador Conta Recebedora",
+                "digitoVerificadoraContaRecebedora": "Dígito Verificador Conta Recebedora",
                 "numeroContaCorrenteRecebedora": "Número Conta Corrente Recebedora",
                 "numeroDigitoVerificadorContaCorrenteRecebedora": "Número Dígito Verificador Conta Corrente Recebedora",
                 "nomeClienteRecebedor": "Nome Cliente Recebedor",
@@ -1702,7 +1829,6 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
                 "CNPJFundoInvestimento": " CNPJ Fundo Investimento",
                 "valorCotaExtrato": "Valor Cota Extrato",
                 "dataAfericaoValorCota": "Data Afericão Valor Cota",
-                "ultimaCotacaoCota": "Última Cotação Cota",
                 "dataUltimaCotacaoCota": "Data Última Cotação Cota",
                 "sinalRentabilidadeMes": "Sinal Rentabilidade Mês",
                 "valorRentabilidadeMes": "Valor Rentabilidade Mês",
@@ -1772,6 +1898,11 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         variacao_poupanca: str,
         codigo_variacao: int,
     ) -> pd.DataFrame:
+        """Reaver o extrato de uma variação de poupança da conta.
+
+        Levanta :class:`SemLancamentosError` quando não há o que devolver e
+        :class:`ExtratoError` quando a variação não existe.
+        """
         access_token = self._get_access_token()
 
         res = requests.request(
@@ -1785,9 +1916,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_extrato_aplicacao(res)
 
         res = common.parse_json_object(res)
         return common.handle_results(

{bb_api-0.5.0 → bb_api-0.5.2}/bb_api/common.py

@@ -91,7 +91,7 @@ def handle_results(
 
     if insertables is not None:
         for insertable in insertables:
-            df[insertable] = cast("Scalar", record[insertable])
+            df[insertable] = cast("Scalar", record.get(insertable))
 
     if explodeables is not None:
         for explodeable in explodeables:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bb_api
-Version: 0.5.0
+Version: 0.5.2
 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.2}/pyproject.toml

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