bb_api 0.5.1__tar.gz → 0.5.3__tar.gz

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

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

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

@@ -4,7 +4,7 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("bb_api")
 except PackageNotFoundError:
-    __version__ = "0.5.1"
+    __version__ = "0.5.3"
 
 
 from .common import Ambiente

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

@@ -19,6 +19,9 @@ MAX_DIAS_EXTRATO = 31
 _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.
@@ -43,6 +46,10 @@ class SemLancamentosError(ExtratoError):
     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.
     """
 
 
@@ -64,9 +71,34 @@ def _mensagem_de_erro(res: requests.Response) -> str:
         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()
@@ -77,6 +109,19 @@ def _erro_extrato(res: requests.Response) -> ExtratoError:
     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
@@ -685,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(
@@ -699,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"])
@@ -709,9 +761,10 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         df = common.handle_results(
             extrato,
             main_list="listaLancamentosExtrato",
+            keep_header_when_empty=True,
             insertables=[
                 "numeroAgenciaRecebedora",
-                "digitoVerificadorContaRecebedora",
+                "digitoVerificadoraContaRecebedora",
                 "numeroContaCorrenteRecebedora",
                 "numeroDigitoVerificadorContaCorrenteRecebedora",
                 "nomeClienteRecebedor",
@@ -719,7 +772,6 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
                 "CNPJFundoInvestimento",
                 "valorCotaExtrato",
                 "dataAfericaoValorCota",
-                "ultimaCotacaoCota",
                 "dataUltimaCotacaoCota",
                 "sinalRentabilidadeMes",
                 "valorRentabilidadeMes",
@@ -758,7 +810,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",
@@ -766,7 +818,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",
@@ -837,6 +888,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(
@@ -851,14 +908,13 @@ 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(
             res,
             main_list="listaLancamentos",
+            keep_header_when_empty=True,
             insertables=[
                 "codigoProgramaGoverno",
                 "nomeProgramaGoverno",
@@ -1689,6 +1745,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(
@@ -1703,9 +1767,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"])
@@ -1713,9 +1775,10 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         df = common.handle_results(
             extrato,
             main_list="listaLancamentosExtrato",
+            keep_header_when_empty=True,
             insertables=[
                 "numeroAgenciaRecebedora",
-                "digitoVerificadorContaRecebedora",
+                "digitoVerificadoraContaRecebedora",
                 "numeroContaCorrenteRecebedora",
                 "numeroDigitoVerificadorContaCorrenteRecebedora",
                 "nomeClienteRecebedor",
@@ -1723,7 +1786,6 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
                 "CNPJFundoInvestimento",
                 "valorCotaExtrato",
                 "dataAfericaoValorCota",
-                "ultimaCotacaoCota",
                 "dataUltimaCotacaoCota",
                 "sinalRentabilidadeMes",
                 "valorRentabilidadeMes",
@@ -1762,7 +1824,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",
@@ -1770,7 +1832,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",
@@ -1840,6 +1901,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(
@@ -1853,14 +1919,13 @@ 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(
             res,
             main_list="listaLancamentos",
+            keep_header_when_empty=True,
             insertables=[
                 "codigoProgramaGoverno",
                 "nomeProgramaGoverno",

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

@@ -81,17 +81,31 @@ def handle_results(
     insertables: Sequence[str] | None = None,
     explodeables: Sequence[str] | None = None,
     rename_dict: Mapping[str, str] | None = None,
+    *,
+    keep_header_when_empty: bool = False,
 ) -> pd.DataFrame:
+    """Monta o DataFrame da resposta: uma linha por item de ``main_list``.
+
+    Os campos de ``insertables`` ficam no nível de cima da resposta, fora da
+    lista, e são repetidos em todas as linhas.
+
+    Com ``keep_header_when_empty``, uma lista vazia devolve uma linha só com
+    esses campos, em vez de um DataFrame sem linha nenhuma. É o que preserva o
+    cabeçalho das respostas em que ele carrega o dado principal, como o
+    rendimento do mês nos extratos de aplicação.
+    """
     record = cast("Mapping[str, object]", data)
 
     if main_list is not None:
-        df = pd.DataFrame(cast("list[dict[Hashable, object]]", record[main_list]))
+        itens = cast("list[dict[Hashable, object]]", record.get(main_list) or [])
+        so_cabecalho = not itens and keep_header_when_empty
+        df = pd.DataFrame(index=[0]) if so_cabecalho else pd.DataFrame(itens)
     else:
         df = pd.DataFrame([dict(record)])
 
     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.1 → bb_api-0.5.3}/bb_api.egg-info/PKG-INFO

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

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

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