bb_api 0.4.0__tar.gz → 0.5.0__tar.gz

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

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

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

@@ -1,15 +1,20 @@
-from importlib.metadata import version
+from importlib.metadata import PackageNotFoundError, version
 
 
 try:
     __version__ = version("bb_api")
-except:
-    __version__ = "0.4.0"
+except PackageNotFoundError:
+    __version__ = "0.5.0"
 
 
 from .common import Ambiente
 from .accountability import AccountabilityV3RepasseAPI, AccountabilityV3ControleAPI
-from .sia import BBSiaAPI
+from .sia import (
+    BBSiaAPI,
+    CredenciaisNecessariasError,
+    FalhaDownload,
+    ResultadoDownloads,
+)
 from .gestao_agil import (
     parse_retorno_abertura_massificada,
     ler_retorno_abertura_massificada,
@@ -20,6 +25,9 @@ __all__ = [
     "AccountabilityV3RepasseAPI",
     "AccountabilityV3ControleAPI",
     "BBSiaAPI",
+    "CredenciaisNecessariasError",
+    "FalhaDownload",
+    "ResultadoDownloads",
     "parse_retorno_abertura_massificada",
     "ler_retorno_abertura_massificada",
 ]

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

@@ -85,13 +85,9 @@ class _AccountabilityV3BaseAPI:
                 + "ambiente 'BB_API_CLIENT_SECRET'."
             )
 
-        base64_credentials = (
-            base64
-            .b64encode(
-                f"{client_id}:{client_secret}".encode("utf-8")
-            )
-            .decode("utf-8")
-        )
+        base64_credentials = base64.b64encode(
+            f"{client_id}:{client_secret}".encode("utf-8")
+        ).decode("utf-8")
         self._access_token = ""
         self._base64_credentials = base64_credentials
         self._last_access_token_request_timestamp = None
@@ -126,9 +122,7 @@ class _AccountabilityV3BaseAPI:
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível adquirir as novas credenciais de acesso."
-            )
+            raise Exception("Não foi possível adquirir as novas credenciais de acesso.")
 
         data = common.parse_json_object(res)
         self._access_token = cast("str", data["access_token"])
@@ -230,9 +224,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível reaver o extrato do órgão repassador."
-            )
+            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
 
         res = common.parse_json_object(res)
 
@@ -306,9 +298,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível reaver o extrato do órgão repassador."
-            )
+            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
 
         res = common.parse_json_object(res)
 
@@ -439,9 +429,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível reaver o extrato do órgão repassador."
-            )
+            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
 
         res = common.parse_json_object(res)
 
@@ -573,9 +561,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível reaver o extrato do órgão repassador."
-            )
+            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
 
         res = common.parse_json_object(res)
 
@@ -762,7 +748,9 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
             },
         )
 
-        df["Código Programa Governo"] = cast("common.Scalar", res["codigoProgramaGoverno"])
+        df["Código Programa Governo"] = cast(
+            "common.Scalar", res["codigoProgramaGoverno"]
+        )
         df["Nome Programa Governo"] = cast("common.Scalar", res["nomeProgramaGoverno"])
         df["Código SubPrograma Governo"] = cast(
             "common.Scalar", res["codigoSubProgramaGoverno"]
@@ -1245,9 +1233,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível reaver o extrato do órgão repassador."
-            )
+            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
 
         res = common.parse_json_object(res)
 
@@ -1321,9 +1307,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível reaver o extrato do órgão repassador."
-            )
+            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
 
         res = common.parse_json_object(res)
 
@@ -1454,9 +1438,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível reaver o extrato do órgão repassador."
-            )
+            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
 
         res = common.parse_json_object(res)
 
@@ -1770,7 +1752,9 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
             },
         )
 
-        df["Código Programa Governo"] = cast("common.Scalar", res["codigoProgramaGoverno"])
+        df["Código Programa Governo"] = cast(
+            "common.Scalar", res["codigoProgramaGoverno"]
+        )
         df["Nome Programa Governo"] = cast("common.Scalar", res["nomeProgramaGoverno"])
         df["Código SubPrograma Governo"] = cast(
             "common.Scalar", res["codigoSubProgramaGoverno"]

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

@@ -42,11 +42,6 @@ _sia_domains = {
 
 
 def sia_domain_for(ambiente: Ambiente) -> str:
-    """Devolve o domínio do BB Sia (GMT-EDI) correspondente ao ``ambiente``.
-
-    Lança ``ValueError`` para ambientes que o BB Sia não atende (como o
-    ``HOMOLOGACAO_ALTERNATIVO``).
-    """
     domain = _sia_domains.get(ambiente)
     if domain is None:
         raise ValueError(

{bb_api-0.4.0 → bb_api-0.5.0}/bb_api/gestao_agil.py

@@ -1,19 +1,7 @@
-"""Parser para arquivos de retorno MCIF470 (abertura de contas massificadas).
-
-Esses arquivos são disponibilizados pela API GMT-SIA do Banco do Brasil
-(``gmtedi.bb.com.br/gmt-sia-api``), no contexto do sistema Gestão Ágil, e seguem
-um layout de largura fixa de 150 posições por linha, conforme a aba
-"MCIF470-Abertura RETORNO" da planilha de leiaute de abertura massificada.
-
-Cada linha é identificada pelas 5 primeiras posições:
-
-    HEADER  -> "00000"
-    TRAILER -> "99999"
-    DETALHE -> demais
-"""
-
 import os
+import warnings
 from collections.abc import Mapping, Sequence
+from datetime import date
 
 import pandas as pd
 
@@ -24,11 +12,9 @@ _HEADER_ID = "00000"
 _TRAILER_ID = "99999"
 _LINE_LENGTH = 150
 
-# Cada campo: (nome, posição inicial, posição final, formato).
-# Posições 1-based e inclusivas, como na planilha de leiaute.
 _HEADER_LAYOUT = [
     ("preenchimento",        1,   5,  "N"),
-    ("data_remessa",         6,  13,  "N"),  # DDMMAAAA
+    ("data_remessa",         6,  13,  "A"),
     ("nome_arquivo",        14,  21,  "A"),
     ("numero_processo",     22,  26,  "N"),
     ("sequencial_remessa",  27,  31,  "N"),
@@ -38,21 +24,21 @@ _HEADER_LAYOUT = [
 
 _DETALHE_LAYOUT = [
     ("sequencial",                    1,   5,  "N"),
-    ("cpf_cnpj",                      6,  19,  "N"),
-    ("data_nascimento",             20,  27,  "N"),  # DDMMAAAA
+    ("cpf_cnpj",                      6,  19,  "ID"),
+    ("data_nascimento",             20,  27,  "A"),
     ("nome_cliente",                28,  87,  "A"),
     ("uso_cliente",                 88,  95,  "A"),
-    ("numero_programa_gestao_agil", 96, 104,  "A"),
-    ("agencia_cliente",            105, 108,  "N"),
-    ("dv_agencia_cliente",         109, 109,  "N"),
-    ("grupo_setex",                110, 111,  "N"),
-    ("dv_grupo_setex",             112, 112,  "N"),
-    ("conta",                      113, 123,  "N"),
-    ("dv_conta",                   124, 124,  "N"),
-    ("ocorrencia_cliente",         125, 127,  "N"),
-    ("ocorrencia_conta",           128, 130,  "N"),
-    ("ocorrencia_limite_credito",  131, 133,  "N"),
-    ("codigo_mci",                 134, 142,  "N"),
+    ("numero_programa_gestao_agil", 96, 104,  "ID"),
+    ("agencia_cliente",            105, 108,  "ID"),
+    ("dv_agencia_cliente",         109, 109,  "ID"),
+    ("grupo_setex",                110, 111,  "ID"),
+    ("dv_grupo_setex",             112, 112,  "ID"),
+    ("conta",                      113, 123,  "ID"),
+    ("dv_conta",                   124, 124,  "ID"),
+    ("ocorrencia_cliente",         125, 127,  "ID"),
+    ("ocorrencia_conta",           128, 130,  "ID"),
+    ("ocorrencia_limite_credito",  131, 133,  "ID"),
+    ("codigo_mci",                 134, 142,  "ID"),
     ("espacos_em_branco",          143, 150,  "A"),
 ]
 
@@ -62,7 +48,6 @@ _TRAILER_LAYOUT = [
     ("espacos_em_branco",    15, 150,  "A"),
 ]
 
-# Tabela 1 - Ocorrências do Cliente
 _TABELA_OCORRENCIA_CLIENTE = {
     "001": "tipo pessoa inválido",
     "002": "tipo CPF/CNPJ inválido",
@@ -82,7 +67,6 @@ _TABELA_OCORRENCIA_CLIENTE = {
     "017": "tipo de pessoa não permitido para esse processo/tipo de repasse",
 }
 
-# Tabela 2 - Ocorrências da Conta
 _TABELA_OCORRENCIA_CONTA = {
     "001": "ind cheque especial inválido",
     "002": "setex/dv inválido",
@@ -90,7 +74,6 @@ _TABELA_OCORRENCIA_CONTA = {
     "004": "dados pessoa física divergente",
 }
 
-# Tabela 3 - Ocorrências do Limite de Crédito
 _TABELA_OCORRENCIA_LIMITE = {
     "001": "cod estado civil inválido",
     "002": "cod natureza ocupação inválido",
@@ -102,7 +85,6 @@ _TABELA_OCORRENCIA_LIMITE = {
     "008": "nao atende ao credit scoring",
 }
 
-# Colunas de preenchimento/controle que não interessam ao DataFrame final.
 _COLUNAS_DESCARTADAS = ["tipo", "espacos_em_branco"]
 
 _RENAME_DETALHE = {
@@ -136,7 +118,6 @@ def _parse_fields(
     linha: str,
     layout: Sequence[tuple[str, int, int, str]],
 ) -> dict[str, str | int]:
-    """Fatia a linha conforme o layout. Campos "N" viram int quando possível."""
     rec: dict[str, str | int] = {}
     for nome, ini, fim, fmt in layout:
         valor = linha[ini - 1:fim].strip()
@@ -147,8 +128,28 @@ def _parse_fields(
     return rec
 
 
+def _parse_data_ddmmaaaa(valor: object) -> str | None:
+    texto = str(valor).strip().zfill(8)
+    if texto == "0" * 8 or len(texto) != 8 or not texto.isdigit():
+        return None
+    dia, mes, ano = texto[:2], texto[2:4], texto[4:]
+    try:
+        return date(int(ano), int(mes), int(dia)).isoformat()
+    except ValueError:
+        return None
+
+
+def _parse_cpf_cnpj(valor: str) -> dict[str, str] | None:
+    digitos = "".join(c for c in valor if c.isdigit())
+    if not digitos.strip("0"):
+        return None
+    significativos = digitos.lstrip("0")
+    if len(significativos) <= 11:
+        return {"valor": digitos[-11:].zfill(11), "tipo": "cpf"}
+    return {"valor": digitos.zfill(14), "tipo": "cnpj"}
+
+
 def _decode_ocorrencia(codigo: object, tabela: Mapping[str, str]) -> str | None:
-    """Descrição da ocorrência; None para "000"/vazio/sem código."""
     cod = str(codigo).zfill(3) if str(codigo).strip() else ""
     if cod in ("", "000"):
         return None
@@ -156,7 +157,6 @@ def _decode_ocorrencia(codigo: object, tabela: Mapping[str, str]) -> str | None:
 
 
 def _parse_linha(linha: str, numero: int) -> dict[str, object] | None:
-    """Parseia uma linha e devolve um dict com o tipo de registro e os campos."""
     linha = linha.rstrip("\r\n")
     if not linha.strip():
         return None
@@ -166,15 +166,27 @@ def _parse_linha(linha: str, numero: int) -> dict[str, object] | None:
 
     ident = linha[:5]
     if ident == _HEADER_ID:
-        return {"tipo": "HEADER", "linha": numero, **_parse_fields(linha, _HEADER_LAYOUT)}
+        header: dict[str, object] = {
+            "tipo": "HEADER",
+            "linha": numero,
+            **_parse_fields(linha, _HEADER_LAYOUT),
+        }
+        header["data_remessa"] = _parse_data_ddmmaaaa(header["data_remessa"])
+        return header
     if ident == _TRAILER_ID:
-        return {"tipo": "TRAILER", "linha": numero, **_parse_fields(linha, _TRAILER_LAYOUT)}
+        return {
+            "tipo": "TRAILER",
+            "linha": numero,
+            **_parse_fields(linha, _TRAILER_LAYOUT),
+        }
 
     rec: dict[str, object] = {
         "tipo": "DETALHE",
         "linha": numero,
         **_parse_fields(linha, _DETALHE_LAYOUT),
     }
+    rec["cpf_cnpj"] = _parse_cpf_cnpj(str(rec["cpf_cnpj"]))
+    rec["data_nascimento"] = _parse_data_ddmmaaaa(rec["data_nascimento"])
     rec["ocorrencia_cliente_desc"] = _decode_ocorrencia(
         rec["ocorrencia_cliente"], _TABELA_OCORRENCIA_CLIENTE)
     rec["ocorrencia_conta_desc"] = _decode_ocorrencia(
@@ -185,18 +197,6 @@ def _parse_linha(linha: str, numero: int) -> dict[str, object] | None:
 
 
 def parse_retorno_abertura_massificada(conteudo: str) -> pd.DataFrame:
-    """Parseia o conteúdo de um arquivo de retorno MCIF470 (abertura de contas
-    massificadas) e devolve um ``DataFrame`` com os registros de DETALHE.
-
-    Os códigos de ocorrência são decodificados em colunas descritivas e os
-    metadados do cabeçalho (número do processo, data e sequencial da remessa)
-    são repetidos em todas as linhas para facilitar a rastreabilidade.
-
-    Parâmetros
-    ----------
-    conteudo: str
-        Conteúdo textual completo do arquivo de retorno.
-    """
     registros: list[dict[str, object]] = []
     for numero, linha in enumerate(conteudo.splitlines(), start=1):
         rec = _parse_linha(linha, numero)
@@ -211,6 +211,16 @@ def parse_retorno_abertura_massificada(conteudo: str) -> pd.DataFrame:
             header = registro
             break
 
+    trailer = next((r for r in registros if r["tipo"] == "TRAILER"), None)
+    if trailer is not None:
+        esperado = trailer.get("quantidade_registros")
+        if isinstance(esperado, int) and esperado != len(registros):
+            warnings.warn(
+                f"Trailer indica {esperado} registros, mas {len(registros)}"
+                + " foram lidos do arquivo.",
+                stacklevel=2,
+            )
+
     data = {
         "detalhes": detalhes,
         "numero_processo": header.get("numero_processo"),
@@ -234,18 +244,6 @@ def ler_retorno_abertura_massificada(
     caminho: str | os.PathLike[str],
     encoding: str = "latin-1",
 ) -> pd.DataFrame:
-    """Lê um arquivo de retorno MCIF470 do disco e o parseia.
-
-    Atalho para ``parse_retorno_abertura_massificada`` quando o arquivo já está
-    salvo localmente.
-
-    Parâmetros
-    ----------
-    caminho: str | os.PathLike
-        Caminho do arquivo de retorno a ser lido.
-    encoding: str
-        Codificação do arquivo (padrão: ``latin-1``).
-    """
     with open(caminho, "r", encoding=encoding) as arquivo:
         conteudo = arquivo.read()
     return parse_retorno_abertura_massificada(conteudo)

{bb_api-0.4.0 → bb_api-0.5.0}/bb_api/sia.py

@@ -1,39 +1,20 @@
-"""Encapsulador da API BB Sia (Gestão Ágil) do Banco do Brasil.
-
-O BB Sia é acessado pelo domínio do GMT-EDI (``gmtedi.bb.com.br`` em produção) e
-expõe, entre outros, os seguintes grupos de endpoints:
-
-* ``gmt-autorizador-api`` -- autorização (usuário/senha e refresh token) e
-  revogação de tokens;
-* ``gmt-catalogo-api`` -- catálogo dos uploads possíveis;
-* ``gmt-sia-api`` -- envio (upload) e recebimento (download) de arquivos, além
-  da consulta de downloads e dos seus metadados;
-* ``gmt-protocolo-api`` -- consulta de protocolos.
-
-Diferente da API ``Accountability``, a autorização do BB Sia não usa o fluxo
-``client_credentials`` do ``oauth.bb.com.br``: ela usa o *grant* ``password``
-(usuário e senha) ou ``refresh_token`` contra o próprio GMT-EDI, devolvendo um
-``access_token`` e um ``refresh_token``.
-
-.. note::
-    Os nomes das listas e colunas devolvidas pelos endpoints de consulta
-    (``listaUploads``, ``listaDownloads``, ``listaProtocolos`` e metadados) são
-    inferidos a partir da semântica de cada endpoint, pois não há um leiaute de
-    resposta publicado na coleção de referência. Por isso esses métodos não
-    renomeiam as colunas: ajuste o tratamento conforme a resposta real da API.
-"""
-
 import os
 import base64
 import hashlib
 import datetime
-from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from collections.abc import Callable, Mapping, Sequence
 from typing import cast
 
 import pandas as pd
 import requests
 
 import bb_api.common as common
+import bb_api.gestao_agil as gestao_agil
+
+
+class CredenciaisNecessariasError(Exception):
+    pass
 
 
 def _to_dataframe(
@@ -41,13 +22,6 @@ def _to_dataframe(
     main_list: str | None = None,
     rename_dict: Mapping[str, str] | None = None,
 ) -> pd.DataFrame:
-    """Constrói um ``DataFrame`` a partir de uma resposta de esquema desconhecido.
-
-    Usa ``main_list`` quando essa chave existe e aponta para uma lista; caso
-    contrário, usa a primeira lista encontrada na resposta e, se não houver
-    nenhuma, trata a resposta inteira como um único registro. Assim os endpoints
-    de consulta do BB Sia não quebram mesmo sem um leiaute de resposta conhecido.
-    """
     record = cast("Mapping[str, object]", res)
 
     if main_list is not None and isinstance(record.get(main_list), list):
@@ -61,22 +35,11 @@ def _to_dataframe(
 
 
 def _content_md5(conteudo: bytes) -> str:
-    """Calcula o cabeçalho ``Content-MD5`` (digest MD5 em base64, RFC 1864).
-
-    Usa ``usedforsecurity=False`` porque o MD5 aqui é de integridade, não
-    criptográfico -- isso também evita ``ValueError`` em builds FIPS do Python.
-    """
     digest = hashlib.md5(conteudo, usedforsecurity=False).digest()
     return base64.b64encode(digest).decode("utf-8")
 
 
 def _to_iso_z(value: common.DateLike, *, fim_do_dia: bool = False) -> str:
-    """Formata uma data no padrão ISO-8601 com milissegundos e sufixo ``Z``.
-
-    Strings são repassadas sem alteração (o chamador controla o formato exato).
-    Para ``date``/``datetime`` sem hora, usa ``00:00:00`` ou ``23:59:59`` (quando
-    ``fim_do_dia``), como nos exemplos de ``dtCriacaoMin``/``dtCriacaoMax``.
-    """
     if isinstance(value, str):
         return value
 
@@ -90,15 +53,20 @@ def _to_iso_z(value: common.DateLike, *, fim_do_dia: bool = False) -> str:
     return dt.strftime("%Y-%m-%dT%H:%M:%S.000Z")
 
 
-class BBSiaAPI:
-    """Encapsulador da API BB Sia (Gestão Ágil) do Banco do Brasil.
+@dataclass(frozen=True)
+class FalhaDownload:
+    id_arquivo: int | str | None
+    nome_arquivo: str | None
+    erro: str
 
-    O token de acesso é gerenciado automaticamente: a instância reaproveita o
-    token por 10 minutos e gera um novo quando necessário, preferindo o
-    ``refresh_token`` e caindo para usuário/senha quando ele não está disponível
-    ou expirou.
-    """
 
+@dataclass(frozen=True)
+class ResultadoDownloads:
+    dados: pd.DataFrame
+    falhas: list[FalhaDownload]
+
+
+class BBSiaAPI:
     _scope: str
     _sia_domain: str
     _access_token: str
@@ -116,43 +84,18 @@ class BBSiaAPI:
         refresh_token: str | None = None,
         scope: str = "sia:usuario",
     ):
-        """Inicia uma instância do encapsulador da API BB Sia do Banco do Brasil.
-
-        Parâmetros
-        ----------
-        ambiente: common.Ambiente
-            Ambiente de execução. O BB Sia não possui ambiente alternativo
-            (sandbox).
-        username: str | None
-            Nome de usuário para o *grant* ``password``. Lido da variável de
-            ambiente ``BBS_USERNAME`` quando não informado.
-        password: str | None
-            Senha para o *grant* ``password``. Lida da variável de ambiente
-            ``BBS_PASSWORD`` quando não informada.
-        refresh_token: str | None
-            Refresh token para o *grant* ``refresh_token``. Lido da variável de
-            ambiente ``BBS_REFRESH_TOKEN`` quando não informado.
-        scope: str
-            Escopo solicitado no *grant* ``password`` (padrão ``sia:usuario``).
-
-        É obrigatório fornecer um ``refresh_token`` ou o par usuário/senha.
-        """
         self._ambiente = ambiente
         self._sia_domain = common.sia_domain_for(ambiente)
         self._scope = scope
 
-        self._username = username if username is not None else os.getenv("BBS_USERNAME")
-        self._password = password if password is not None else os.getenv("BBS_PASSWORD")
-        self._refresh_token = (
-            refresh_token if refresh_token is not None else os.getenv("BBS_REFRESH_TOKEN")
-        )
+        self._username = username
+        self._password = password
+        self._refresh_token = refresh_token
 
         if not self._refresh_token and not (self._username and self._password):
             raise ValueError(
                 "Credenciais inválidas para o BB Sia. Forneça um 'refresh_token'"
-                + " (ou a variável de ambiente 'BBS_REFRESH_TOKEN') ou o par"
-                + " usuário/senha (parâmetros 'username'/'password' ou as"
-                + " variáveis de ambiente 'BBS_USERNAME'/'BBS_PASSWORD')."
+                + " ou o par usuário/senha (parâmetros 'username'/'password')."
             )
 
         self._access_token = ""
@@ -161,9 +104,16 @@ class BBSiaAPI:
     def _store_access_token(self, data: dict[str, object]) -> dict[str, object]:
         access_token = data.get("access_token")
         if not access_token:
-            raise Exception("A resposta de autorização do BB Sia não trouxe um 'access_token'.")
+            raise Exception(
+                "A resposta de autorização do BB Sia não trouxe um 'access_token'."
+            )
 
         self._access_token = cast("str", access_token)
+
+        refresh_token = data.get("refresh_token")
+        if refresh_token:
+            self._refresh_token = cast("str", refresh_token)
+
         self._last_access_token_request_timestamp = datetime.datetime.now()
         return data
 
@@ -185,22 +135,26 @@ class BBSiaAPI:
             },
         )
 
+        if res.status_code in (400, 401):
+            raise CredenciaisNecessariasError(
+                "Usuário ou senha do BB Sia inválidos ou expirados. Forneça"
+                + " credenciais válidas."
+            )
         if res.status_code != 200:
-            raise Exception("Não foi possível autorizar o acesso ao BB Sia com usuário e senha.")
-
-        data = common.parse_json_object(res)
-        refresh_token = data.get("refresh_token")
-        if refresh_token:
-            self._refresh_token = cast("str", refresh_token)
+            raise Exception(
+                "Não foi possível autorizar o acesso ao BB Sia com usuário e senha."
+            )
 
-        return self._store_access_token(data)
+        return self._store_access_token(common.parse_json_object(res))
 
     def _refresh_grant(
         self,
         validade_refresh_token: int | None = None,
     ) -> dict[str, object]:
         if not self._refresh_token:
-            raise ValueError("Nenhum refresh token disponível para renovar o acesso ao BB Sia.")
+            raise ValueError(
+                "Nenhum refresh token disponível para renovar o acesso ao BB Sia."
+            )
 
         data = {
             "grant_type": "refresh_token",
@@ -216,6 +170,12 @@ class BBSiaAPI:
             data=data,
         )
 
+        if res.status_code in (400, 401):
+            raise CredenciaisNecessariasError(
+                "O refresh token do BB Sia expirou ou é inválido. Informe usuário"
+                + " e senha para reautenticar"
+                + " ('autorizar_novo_token(username, password)')."
+            )
         if res.status_code != 200:
             raise Exception("Não foi possível renovar o token de acesso ao BB Sia.")
 
@@ -235,55 +195,43 @@ class BBSiaAPI:
 
         if self._refresh_token:
             try:
-                self._refresh_grant()
+                _ = self._refresh_grant()
                 return
-            except Exception:
+            except CredenciaisNecessariasError:
                 if not (self._username and self._password):
                     raise
 
-        self._password_grant()
+        if not (self._username and self._password):
+            raise CredenciaisNecessariasError(
+                "Não há refresh token nem usuário/senha para autenticar no BB"
+                + " Sia. Forneça as credenciais"
+                + " ('autorizar_novo_token(username, password)')."
+            )
+
+        _ = self._password_grant()
 
     def _get_access_token(self) -> str:
         self._check_and_update_access_token()
         return self._access_token
 
-    def autorizar_novo_token(self) -> dict[str, object]:
-        """Solicita um novo token via *grant* ``password`` (usuário e senha).
-
-        Atualiza o token de acesso e o refresh token da instância e devolve a
-        resposta crua da API (com ``access_token``, ``refresh_token`` etc.).
-        """
+    def autorizar_novo_token(
+        self,
+        username: str | None = None,
+        password: str | None = None,
+    ) -> dict[str, object]:
+        if username is not None:
+            self._username = username
+        if password is not None:
+            self._password = password
         return self._password_grant()
 
     def renovar_token(
         self,
         validade_refresh_token: int | None = None,
     ) -> dict[str, object]:
-        """Obtém um novo **token de acesso** a partir do refresh token.
-
-        Usa o *grant* ``refresh_token``. O refresh token em si não é renovado
-        nem substituído por esta chamada -- apenas um novo ``access_token`` é
-        devolvido (e passa a ser usado pela instância).
-
-        Parâmetros
-        ----------
-        validade_refresh_token: int | None
-            Validade, em dias, do refresh token atual. ``0`` deixa o refresh
-            token com validade indefinida. Quando ``None``, o parâmetro não é
-            enviado e vale o padrão do Banco do Brasil (1 dia).
-        """
         return self._refresh_grant(validade_refresh_token)
 
     def revogar_token(self, token: str, token_type_hint: str) -> None:
-        """Revoga um token de acesso ou de refresh.
-
-        Parâmetros
-        ----------
-        token: str
-            Valor do token a ser revogado.
-        token_type_hint: str
-            ``"access_token"`` ou ``"refresh_token"``.
-        """
         res = requests.request(
             "POST",
             f"{self._sia_domain}/gmt-autorizador-api/revogar",
@@ -298,10 +246,6 @@ class BBSiaAPI:
             raise Exception("Não foi possível revogar o token do BB Sia.")
 
     def listar_uploads_possiveis(self) -> pd.DataFrame:
-        """Lista os uploads (FTAs) que o usuário pode enviar.
-
-        Endpoint ``GET /gmt-catalogo-api/listaUploads/``.
-        """
         access_token = self._get_access_token()
 
         res = requests.request(
@@ -315,11 +259,7 @@ class BBSiaAPI:
 
         return _to_dataframe(common.parse_json_object(res))
 
-    def listar_downloads(self) -> pd.DataFrame:
-        """Lista os arquivos disponíveis para download.
-
-        Endpoint ``GET /gmt-sia-api/listaDownloads``.
-        """
+    def _fetch_downloads(self) -> dict[str, object]:
         access_token = self._get_access_token()
 
         res = requests.request(
@@ -331,24 +271,16 @@ class BBSiaAPI:
         if res.status_code != 200:
             raise Exception("Não foi possível listar os downloads do BB Sia.")
 
-        return _to_dataframe(common.parse_json_object(res))
+        return common.parse_json_object(res)
+
+    def listar_downloads(self) -> pd.DataFrame:
+        return _to_dataframe(self._fetch_downloads())
 
     def consultar_metadados(
         self,
         id_arquivo: int | str,
         nome_arquivo: str,
     ) -> pd.DataFrame:
-        """Consulta os metadados de um arquivo disponível para download.
-
-        Endpoint ``GET /gmt-sia-api/listaDownloads/{id_arquivo}/{nome_arquivo}``.
-
-        Parâmetros
-        ----------
-        id_arquivo: int | str
-            Identificador do arquivo, como consta ao consultar os downloads.
-        nome_arquivo: str
-            Nome do arquivo, como consta ao consultar os downloads.
-        """
         access_token = self._get_access_token()
 
         res = requests.request(
@@ -358,7 +290,9 @@ class BBSiaAPI:
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível consultar os metadados do arquivo no BB Sia.")
+            raise Exception(
+                "Não foi possível consultar os metadados do arquivo no BB Sia."
+            )
 
         return _to_dataframe(common.parse_json_object(res))
 
@@ -368,21 +302,6 @@ class BBSiaAPI:
         nome_arquivo: str,
         caminho: str | os.PathLike[str] | None = None,
     ) -> bytes:
-        """Baixa o conteúdo de um arquivo do BB Sia.
-
-        Endpoint ``GET /gmt-sia-api/download/{id_arquivo}/{nome_arquivo}``.
-
-        Parâmetros
-        ----------
-        id_arquivo: int | str
-            Identificador do arquivo, como consta ao consultar os downloads.
-        nome_arquivo: str
-            Nome do arquivo, como consta ao consultar os downloads.
-        caminho: str | os.PathLike | None
-            Quando informado, o conteúdo também é gravado nesse caminho.
-
-        Devolve o conteúdo do arquivo em ``bytes``.
-        """
         access_token = self._get_access_token()
 
         res = requests.request(
@@ -396,10 +315,60 @@ class BBSiaAPI:
 
         if caminho is not None:
             with open(caminho, "wb") as arquivo:
-                arquivo.write(res.content)
+                _ = arquivo.write(res.content)
 
         return res.content
 
+    def processar_downloads(
+        self,
+        parser: Callable[[str], pd.DataFrame] = gestao_agil.parse_retorno_abertura_massificada,
+        encoding: str = "latin-1",
+    ) -> ResultadoDownloads:
+        listagem = self._fetch_downloads()
+        arquivos = listagem.get("arquivos")
+        if not isinstance(arquivos, list):
+            return ResultadoDownloads(dados=pd.DataFrame(), falhas=[])
+
+        frames: list[pd.DataFrame] = []
+        falhas: list[FalhaDownload] = []
+
+        for arquivo in cast("list[object]", arquivos):
+            meta = cast("Mapping[str, object]", arquivo)
+            id_arquivo = cast("int | str | None", meta.get("id"))
+            nome_arquivo = cast("str | None", meta.get("nome"))
+            cod_fta = cast("int | str | None", meta.get("codFta"))
+
+            if id_arquivo is None or nome_arquivo is None:
+                falhas.append(
+                    FalhaDownload(
+                        id_arquivo=id_arquivo,
+                        nome_arquivo=nome_arquivo,
+                        erro="Download sem 'id' ou 'nome' na listagem do BB Sia.",
+                    )
+                )
+                continue
+
+            try:
+                conteudo = self.baixar_arquivo(id_arquivo, nome_arquivo)
+                df = parser(conteudo.decode(encoding))
+            except Exception as exc:
+                falhas.append(
+                    FalhaDownload(
+                        id_arquivo=id_arquivo,
+                        nome_arquivo=nome_arquivo,
+                        erro=str(exc),
+                    )
+                )
+                continue
+
+            df.insert(0, "ID Arquivo", id_arquivo)
+            df.insert(1, "Nome Arquivo", nome_arquivo)
+            df.insert(2, "Código FTA", cod_fta)
+            frames.append(df)
+
+        dados = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+        return ResultadoDownloads(dados=dados, falhas=falhas)
+
     def pre_upload(
         self,
         fta: int | str,
@@ -408,28 +377,6 @@ class BBSiaAPI:
         evento: int | str = 1,
         content_md5: str | None = None,
     ) -> requests.Response:
-        """Negocia (HEAD) o envio de um arquivo antes do upload.
-
-        Endpoint ``HEAD /gmt-sia-api/upload/{fta}/{evento}/{nome_arquivo}``.
-
-        Não levanta exceção em respostas não-2xx nem segue redirecionamentos
-        automaticamente: o ``status_code`` e os cabeçalhos da resposta fazem
-        parte da negociação (por exemplo, para retomar um envio). Inspecione a
-        ``requests.Response`` devolvida.
-
-        Parâmetros
-        ----------
-        fta: int | str
-            Número do FTA para o qual o arquivo será enviado.
-        nome_arquivo: str
-            Nome do arquivo a ser enviado.
-        conteudo: bytes
-            Conteúdo do arquivo, usado para calcular MD5 e tamanho.
-        evento: int | str
-            Etapa de recepção (por padrão, ``1``).
-        content_md5: str | None
-            Sobrescreve o ``Content-MD5`` calculado (digest MD5 em base64).
-        """
         access_token = self._get_access_token()
         md5 = content_md5 if content_md5 is not None else _content_md5(conteudo)
 
@@ -455,35 +402,6 @@ class BBSiaAPI:
         total_bytes: int | None = None,
         content_md5: str | None = None,
     ) -> requests.Response:
-        """Envia (PUT) um arquivo, ou um trecho dele, para o BB Sia.
-
-        Endpoint ``PUT /gmt-sia-api/upload/{fta}/{evento}/{nome_arquivo}``.
-
-        Levanta exceção apenas em respostas de erro (``status_code >= 400``).
-        Redirecionamentos não são seguidos automaticamente: respostas de
-        continuação (como ``308``) são devolvidas para o chamador decidir, o
-        que permite envios fracionados.
-
-        Parâmetros
-        ----------
-        fta: int | str
-            Número do FTA para o qual o arquivo será enviado.
-        nome_arquivo: str
-            Nome do arquivo a ser enviado.
-        conteudo: bytes
-            Bytes a serem enviados nesta requisição (o arquivo todo ou um trecho).
-        evento: int | str
-            Etapa de recepção (por padrão, ``1``).
-        byte_inicial: int
-            Primeiro byte deste trecho, para o cabeçalho ``Content-Range``.
-        byte_final: int | None
-            Último byte deste trecho. Quando ``None``, assume o último byte de
-            ``conteudo`` (``byte_inicial + len(conteudo) - 1``).
-        total_bytes: int | None
-            Tamanho total do arquivo. Quando ``None``, assume ``len(conteudo)``.
-        content_md5: str | None
-            Sobrescreve o ``Content-MD5`` calculado (digest MD5 em base64).
-        """
         access_token = self._get_access_token()
         md5 = content_md5 if content_md5 is not None else _content_md5(conteudo)
 
@@ -519,30 +437,6 @@ class BBSiaAPI:
         dt_criacao_min: common.DateLike | None = None,
         dt_criacao_max: common.DateLike | None = None,
     ) -> pd.DataFrame:
-        """Consulta protocolos no BB Sia.
-
-        Endpoint ``POST /gmt-protocolo-api/listaProtocolos``. Apenas os filtros
-        informados (diferentes de ``None``) são enviados no corpo da requisição.
-
-        Parâmetros
-        ----------
-        pagina: int
-            Página da consulta (``metadata.pagina``).
-        por_pagina: int
-            Quantidade de itens por página (``metadata.porPagina``).
-        protocolo: Sequence[int] | None
-            Números de protocolo a filtrar.
-        cod_fta: Sequence[int] | None
-            Códigos de FTA a filtrar.
-        cod_estado_protocolo: Sequence[int] | None
-            Códigos de estado do protocolo a filtrar.
-        dt_criacao_min: common.DateLike | None
-            Data de criação mínima. ``date``/``datetime`` viram o início do dia
-            em ISO-8601 com sufixo ``Z``; ``str`` é repassada como veio.
-        dt_criacao_max: common.DateLike | None
-            Data de criação máxima. ``date``/``datetime`` viram o fim do dia em
-            ISO-8601 com sufixo ``Z``; ``str`` é repassada como veio.
-        """
         access_token = self._get_access_token()
 
         body: dict[str, object] = {

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "bb_api"
-version = "0.4.0"
+version = "0.5.0"
 description = "Wrapper da API do Banco do Brasil."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -16,9 +16,14 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools]
 packages = ["bb_api"]
 
+[tool.ruff]
+line-length = 99
+
 [dependency-groups]
 dev = [
+    "basedpyright>=1.39.8",
     "pandas-stubs>=3.0.3.260530",
+    "ruff>=0.15.19",
 ]
 
 [tool.semantic_release]