bb_api 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bb_api
-Version: 0.3.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.3.0 → bb_api-0.5.0}/bb_api/__init__.py

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

{bb_api-0.3.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.3.0 → bb_api-0.5.0}/bb_api/common.py

@@ -16,6 +16,10 @@ homo_api_domain = "https://api.hm.bb.com.br"
 homo_alt_api_domain = "https://api.sandbox.bb.com.br"
 prod_api_domain = "https://api.bb.com.br"
 
+dese_sia_domain = "https://gmtedi.desenv.bb.com.br"
+homo_sia_domain = "https://gmtedi.hm.bb.com.br"
+prod_sia_domain = "https://gmtedi.bb.com.br"
+
 time_between_access_token_requests = timedelta(minutes=10)
 
 
@@ -30,6 +34,22 @@ class Ambiente(Enum):
     PRODUCAO = 3
 
 
+_sia_domains = {
+    Ambiente.DESENVOLVIMENTO: dese_sia_domain,
+    Ambiente.HOMOLOGACAO: homo_sia_domain,
+    Ambiente.PRODUCAO: prod_sia_domain,
+}
+
+
+def sia_domain_for(ambiente: Ambiente) -> str:
+    domain = _sia_domains.get(ambiente)
+    if domain is None:
+        raise ValueError(
+            f"O ambiente '{ambiente.name}' não é suportado pela API BB Sia."
+        )
+    return domain
+
+
 def get_headers(access_token: str) -> dict[str, str]:
     return {
         "Authorization": f"Bearer {access_token}",

{bb_api-0.3.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.5.0/bb_api/sia.py

@@ -0,0 +1,469 @@
+import os
+import base64
+import hashlib
+import datetime
+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(
+    res: object,
+    main_list: str | None = None,
+    rename_dict: Mapping[str, str] | None = None,
+) -> pd.DataFrame:
+    record = cast("Mapping[str, object]", res)
+
+    if main_list is not None and isinstance(record.get(main_list), list):
+        return common.handle_results(res, main_list=main_list, rename_dict=rename_dict)
+
+    for key, value in record.items():
+        if isinstance(value, list):
+            return common.handle_results(res, main_list=key, rename_dict=rename_dict)
+
+    return common.handle_results(res, rename_dict=rename_dict)
+
+
+def _content_md5(conteudo: bytes) -> str:
+    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:
+    if isinstance(value, str):
+        return value
+
+    if isinstance(value, datetime.datetime):
+        dt = value
+    elif fim_do_dia:
+        dt = datetime.datetime.combine(value, datetime.time(23, 59, 59))
+    else:
+        dt = datetime.datetime.combine(value, datetime.time())
+
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.000Z")
+
+
+@dataclass(frozen=True)
+class FalhaDownload:
+    id_arquivo: int | str | None
+    nome_arquivo: str | None
+    erro: str
+
+
+@dataclass(frozen=True)
+class ResultadoDownloads:
+    dados: pd.DataFrame
+    falhas: list[FalhaDownload]
+
+
+class BBSiaAPI:
+    _scope: str
+    _sia_domain: str
+    _access_token: str
+    _username: str | None
+    _password: str | None
+    _refresh_token: str | None
+    _ambiente: common.Ambiente
+    _last_access_token_request_timestamp: datetime.datetime | None
+
+    def __init__(
+        self,
+        ambiente: common.Ambiente = common.Ambiente.HOMOLOGACAO,
+        username: str | None = None,
+        password: str | None = None,
+        refresh_token: str | None = None,
+        scope: str = "sia:usuario",
+    ):
+        self._ambiente = ambiente
+        self._sia_domain = common.sia_domain_for(ambiente)
+        self._scope = scope
+
+        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 o par usuário/senha (parâmetros 'username'/'password')."
+            )
+
+        self._access_token = ""
+        self._last_access_token_request_timestamp = None
+
+    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'."
+            )
+
+        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
+
+    def _password_grant(self) -> dict[str, object]:
+        if not (self._username and self._password):
+            raise ValueError(
+                "Usuário e senha são necessários para o grant 'password' do BB Sia."
+            )
+
+        res = requests.request(
+            "POST",
+            f"{self._sia_domain}/gmt-autorizador-api/autoriza",
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            data={
+                "grant_type": "password",
+                "username": self._username,
+                "password": self._password,
+                "scope": self._scope,
+            },
+        )
+
+        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."
+            )
+
+        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."
+            )
+
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": self._refresh_token,
+        }
+        if validade_refresh_token is not None:
+            data["validade_refresh_token"] = str(validade_refresh_token)
+
+        res = requests.request(
+            "POST",
+            f"{self._sia_domain}/gmt-autorizador-api/autoriza",
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            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.")
+
+        return self._store_access_token(common.parse_json_object(res))
+
+    def _check_and_update_access_token(self) -> None:
+        now = datetime.datetime.now()
+        last_request = self._last_access_token_request_timestamp
+
+        is_token_valid = (
+            self._access_token != ""
+            and last_request is not None
+            and now - last_request <= common.time_between_access_token_requests
+        )
+        if is_token_valid:
+            return
+
+        if self._refresh_token:
+            try:
+                _ = self._refresh_grant()
+                return
+            except CredenciaisNecessariasError:
+                if not (self._username and self._password):
+                    raise
+
+        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,
+        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]:
+        return self._refresh_grant(validade_refresh_token)
+
+    def revogar_token(self, token: str, token_type_hint: str) -> None:
+        res = requests.request(
+            "POST",
+            f"{self._sia_domain}/gmt-autorizador-api/revogar",
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            data={
+                "token": token,
+                "token_type_hint": token_type_hint,
+            },
+        )
+
+        if res.status_code not in (200, 204):
+            raise Exception("Não foi possível revogar o token do BB Sia.")
+
+    def listar_uploads_possiveis(self) -> pd.DataFrame:
+        access_token = self._get_access_token()
+
+        res = requests.request(
+            "GET",
+            f"{self._sia_domain}/gmt-catalogo-api/listaUploads/",
+            headers=common.get_headers(access_token),
+        )
+
+        if res.status_code != 200:
+            raise Exception("Não foi possível listar os uploads possíveis no BB Sia.")
+
+        return _to_dataframe(common.parse_json_object(res))
+
+    def _fetch_downloads(self) -> dict[str, object]:
+        access_token = self._get_access_token()
+
+        res = requests.request(
+            "GET",
+            f"{self._sia_domain}/gmt-sia-api/listaDownloads",
+            headers=common.get_headers(access_token),
+        )
+
+        if res.status_code != 200:
+            raise Exception("Não foi possível listar os downloads do BB Sia.")
+
+        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:
+        access_token = self._get_access_token()
+
+        res = requests.request(
+            "GET",
+            f"{self._sia_domain}/gmt-sia-api/listaDownloads/{id_arquivo}/{nome_arquivo}",
+            headers=common.get_headers(access_token),
+        )
+
+        if res.status_code != 200:
+            raise Exception(
+                "Não foi possível consultar os metadados do arquivo no BB Sia."
+            )
+
+        return _to_dataframe(common.parse_json_object(res))
+
+    def baixar_arquivo(
+        self,
+        id_arquivo: int | str,
+        nome_arquivo: str,
+        caminho: str | os.PathLike[str] | None = None,
+    ) -> bytes:
+        access_token = self._get_access_token()
+
+        res = requests.request(
+            "GET",
+            f"{self._sia_domain}/gmt-sia-api/download/{id_arquivo}/{nome_arquivo}",
+            headers=common.get_headers(access_token),
+        )
+
+        if res.status_code != 200:
+            raise Exception("Não foi possível baixar o arquivo do BB Sia.")
+
+        if caminho is not None:
+            with open(caminho, "wb") as arquivo:
+                _ = 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,
+        nome_arquivo: str,
+        conteudo: bytes,
+        evento: int | str = 1,
+        content_md5: str | None = None,
+    ) -> requests.Response:
+        access_token = self._get_access_token()
+        md5 = content_md5 if content_md5 is not None else _content_md5(conteudo)
+
+        return requests.request(
+            "HEAD",
+            f"{self._sia_domain}/gmt-sia-api/upload/{fta}/{evento}/{nome_arquivo}",
+            headers={
+                **common.get_headers(access_token),
+                "Content-MD5": md5,
+                "x-gmt-content-length": str(len(conteudo)),
+            },
+            allow_redirects=False,
+        )
+
+    def upload(
+        self,
+        fta: int | str,
+        nome_arquivo: str,
+        conteudo: bytes,
+        evento: int | str = 1,
+        byte_inicial: int = 0,
+        byte_final: int | None = None,
+        total_bytes: int | None = None,
+        content_md5: str | None = None,
+    ) -> requests.Response:
+        access_token = self._get_access_token()
+        md5 = content_md5 if content_md5 is not None else _content_md5(conteudo)
+
+        total = total_bytes if total_bytes is not None else len(conteudo)
+        fim = byte_final if byte_final is not None else byte_inicial + len(conteudo) - 1
+
+        res = requests.request(
+            "PUT",
+            f"{self._sia_domain}/gmt-sia-api/upload/{fta}/{evento}/{nome_arquivo}",
+            headers={
+                "Content-Type": "application/octet-stream",
+                **common.get_headers(access_token),
+                "Content-MD5": md5,
+                "Content-Length": str(len(conteudo)),
+                "Content-Range": f"bytes {byte_inicial}-{fim}/{total}",
+            },
+            data=conteudo,
+            allow_redirects=False,
+        )
+
+        if res.status_code >= 400:
+            raise Exception("Não foi possível enviar o arquivo para o BB Sia.")
+
+        return res
+
+    def listar_protocolos(
+        self,
+        pagina: int = 1,
+        por_pagina: int = 20,
+        protocolo: Sequence[int] | None = None,
+        cod_fta: Sequence[int] | None = None,
+        cod_estado_protocolo: Sequence[int] | None = None,
+        dt_criacao_min: common.DateLike | None = None,
+        dt_criacao_max: common.DateLike | None = None,
+    ) -> pd.DataFrame:
+        access_token = self._get_access_token()
+
+        body: dict[str, object] = {
+            "metadata": {
+                "pagina": pagina,
+                "porPagina": por_pagina,
+            },
+        }
+        if protocolo is not None:
+            body["protocolo"] = list(protocolo)
+        if cod_fta is not None:
+            body["codFta"] = list(cod_fta)
+        if cod_estado_protocolo is not None:
+            body["codEstadoProtocolo"] = list(cod_estado_protocolo)
+        if dt_criacao_min is not None:
+            body["dtCriacaoMin"] = _to_iso_z(dt_criacao_min)
+        if dt_criacao_max is not None:
+            body["dtCriacaoMax"] = _to_iso_z(dt_criacao_max, fim_do_dia=True)
+
+        res = requests.request(
+            "POST",
+            f"{self._sia_domain}/gmt-protocolo-api/listaProtocolos",
+            headers=common.get_headers(access_token),
+            json=body,
+        )
+
+        if res.status_code != 200:
+            raise Exception("Não foi possível listar os protocolos do BB Sia.")
+
+        return _to_dataframe(common.parse_json_object(res))

{bb_api-0.3.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.3.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.3.0 → bb_api-0.5.0}/bb_api.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ bb_api/__init__.py
 bb_api/accountability.py
 bb_api/common.py
 bb_api/gestao_agil.py
+bb_api/sia.py
 bb_api.egg-info/PKG-INFO
 bb_api.egg-info/SOURCES.txt
 bb_api.egg-info/dependency_links.txt

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

@@ -1,6 +1,6 @@
 [project]
 name = "bb_api"
-version = "0.3.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]