bb_api 0.1.0__py3-none-any.whl

bb_api/common.py

@@ -0,0 +1,83 @@
+import re
+import requests
+import pandas as pd
+from enum import Enum
+from collections.abc import Hashable, Mapping, Sequence
+from datetime import date, datetime, timedelta
+from typing import cast
+
+dese_oauth_domain = "https://oauth.desenv.bb.com.br"
+homo_oauth_domain = "https://oauth.hm.bb.com.br"
+homo_alt_oauth_domain = "https://oauth.sandbox.bb.com.br"
+prod_oauth_domain = "https://oauth.bb.com.br"
+
+dese_api_domain = "https://api.desenv.bb.com.br"
+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"
+
+time_between_access_token_requests = timedelta(minutes=10)
+
+
+type DateLike = str | date | datetime
+type Scalar = str | int | float | bool | None
+
+
+class Ambiente(Enum):
+    DESENVOLVIMENTO = 0
+    HOMOLOGACAO = 1
+    HOMOLOGACAO_ALTERNATIVO = 2
+    PRODUCAO = 3
+
+
+def get_headers(access_token: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {access_token}",
+    }
+
+
+def handle_numeric_string_with_symbols(v: str) -> str:
+    return re.sub(r"\D", "", v)
+
+
+def handle_dates(v: DateLike) -> str:
+    if isinstance(v, str):
+        dt = datetime.strptime(v, "%Y-%m-%d")
+    elif isinstance(v, datetime):
+        dt = v
+    else:
+        dt = datetime.combine(v, datetime.min.time())
+
+    return dt.strftime("%Y-%m-%d")
+
+
+def parse_json_object(res: requests.Response) -> dict[str, object]:
+    return cast("dict[str, object]", res.json())
+
+
+def handle_results(
+    data: object,
+    main_list: str | None = None,
+    insertables: Sequence[str] | None = None,
+    explodeables: Sequence[str] | None = None,
+    rename_dict: Mapping[str, str] | None = None,
+) -> pd.DataFrame:
+    record = cast("Mapping[str, object]", data)
+
+    if main_list is not None:
+        df = pd.DataFrame(cast("list[dict[Hashable, object]]", record[main_list]))
+    else:
+        df = pd.DataFrame([dict(record)])
+
+    if insertables is not None:
+        for insertable in insertables:
+            df[insertable] = cast("Scalar", record[insertable])
+
+    if explodeables is not None:
+        for explodeable in explodeables:
+            df = df.explode(explodeable, ignore_index=True)
+
+    if rename_dict is not None:
+        df = df.rename(rename_dict, axis=1)
+
+    return df

bb_api/gestao_agil.py

@@ -0,0 +1,251 @@
+"""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
+from collections.abc import Mapping, Sequence
+
+import pandas as pd
+
+import bb_api.common as common
+
+
+_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
+    ("nome_arquivo",        14,  21,  "A"),
+    ("numero_processo",     22,  26,  "N"),
+    ("sequencial_remessa",  27,  31,  "N"),
+    ("versao_leiaute",      32,  33,  "N"),
+    ("espacos_em_branco",   34, 150,  "A"),
+]
+
+_DETALHE_LAYOUT = [
+    ("sequencial",                    1,   5,  "N"),
+    ("cpf_cnpj",                      6,  19,  "N"),
+    ("data_nascimento",             20,  27,  "N"),  # DDMMAAAA
+    ("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"),
+    ("espacos_em_branco",          143, 150,  "A"),
+]
+
+_TRAILER_LAYOUT = [
+    ("preenchimento",         1,   5,  "N"),
+    ("quantidade_registros",  6,  14,  "N"),
+    ("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",
+    "003": "CPF/CNPJ inválido",
+    "004": "data nascimento invalida",
+    "005": "nome cliente inválido",
+    "006": "agência/dv inválido",
+    "007": "mais de 5 clientes cadastrados para CPF informado",
+    "008": "cliente BB-Campus fora da faixa etária (16 a 28 anos)",
+    "009": "cliente BBCampus não é pessoa física",
+    "010": "dados pessoa física divergentes",
+    "011": "dados pessoa jurídica divergentes",
+    "013": "cliente BBCampus não titular CPF",
+    "014": "perfil agência incompatível com tipo pessoa",
+    "015": "tipo de pessoa incompátivel com natureza jurídica",
+    "016": "tipo de repasse inválido",
+    "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",
+    "003": "não atende ao credit scoring",
+    "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",
+    "003": "cod ocupação inválido",
+    "004": "valor rendimento inválido",
+    "005": "data rendimento invalida",
+    "006": "tipo contrato trabalho inválido",
+    "007": "data início emprego inválida",
+    "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 = {
+    "linha": "Linha",
+    "sequencial": "Sequencial",
+    "cpf_cnpj": "CPF/CNPJ",
+    "data_nascimento": "Data Nascimento",
+    "nome_cliente": "Nome Cliente",
+    "uso_cliente": "Uso Cliente",
+    "numero_programa_gestao_agil": "Número Programa Gestão Ágil",
+    "agencia_cliente": "Agência Cliente",
+    "dv_agencia_cliente": "DV Agência Cliente",
+    "grupo_setex": "Grupo Setex",
+    "dv_grupo_setex": "DV Grupo Setex",
+    "conta": "Conta",
+    "dv_conta": "DV Conta",
+    "ocorrencia_cliente": "Código Ocorrência Cliente",
+    "ocorrencia_conta": "Código Ocorrência Conta",
+    "ocorrencia_limite_credito": "Código Ocorrência Limite Crédito",
+    "codigo_mci": "Código MCI",
+    "ocorrencia_cliente_desc": "Ocorrência Cliente",
+    "ocorrencia_conta_desc": "Ocorrência Conta",
+    "ocorrencia_limite_credito_desc": "Ocorrência Limite Crédito",
+    "numero_processo": "Número Processo",
+    "data_remessa": "Data Remessa",
+    "sequencial_remessa": "Sequencial Remessa",
+}
+
+
+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()
+        if fmt == "N" and valor.isdigit():
+            rec[nome] = int(valor)
+        else:
+            rec[nome] = valor
+    return rec
+
+
+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
+    return tabela.get(cod, "código desconhecido")
+
+
+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
+
+    if len(linha) < _LINE_LENGTH:
+        linha = linha.ljust(_LINE_LENGTH)
+
+    ident = linha[:5]
+    if ident == _HEADER_ID:
+        return {"tipo": "HEADER", "linha": numero, **_parse_fields(linha, _HEADER_LAYOUT)}
+    if ident == _TRAILER_ID:
+        return {"tipo": "TRAILER", "linha": numero, **_parse_fields(linha, _TRAILER_LAYOUT)}
+
+    rec: dict[str, object] = {
+        "tipo": "DETALHE",
+        "linha": numero,
+        **_parse_fields(linha, _DETALHE_LAYOUT),
+    }
+    rec["ocorrencia_cliente_desc"] = _decode_ocorrencia(
+        rec["ocorrencia_cliente"], _TABELA_OCORRENCIA_CLIENTE)
+    rec["ocorrencia_conta_desc"] = _decode_ocorrencia(
+        rec["ocorrencia_conta"], _TABELA_OCORRENCIA_CONTA)
+    rec["ocorrencia_limite_credito_desc"] = _decode_ocorrencia(
+        rec["ocorrencia_limite_credito"], _TABELA_OCORRENCIA_LIMITE)
+    return rec
+
+
+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)
+        if rec is not None:
+            registros.append(rec)
+
+    detalhes = [r for r in registros if r["tipo"] == "DETALHE"]
+
+    header: dict[str, object] = {}
+    for registro in registros:
+        if registro["tipo"] == "HEADER":
+            header = registro
+            break
+
+    data = {
+        "detalhes": detalhes,
+        "numero_processo": header.get("numero_processo"),
+        "data_remessa": header.get("data_remessa"),
+        "sequencial_remessa": header.get("sequencial_remessa"),
+    }
+    df = common.handle_results(
+        data,
+        main_list="detalhes",
+        insertables=[
+            "numero_processo",
+            "data_remessa",
+            "sequencial_remessa",
+        ],
+        rename_dict=_RENAME_DETALHE,
+    )
+    return df.drop(columns=_COLUNAS_DESCARTADAS, errors="ignore")
+
+
+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.1.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: bb_api
+Version: 0.1.0
+Summary: Wrapper da API do Banco do Brasil.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=3.0.1
+Requires-Dist: requests>=2.32.5
+Dynamic: license-file
+
+# Biblioteca API BB
+
+*Wrapper* da API do Banco do Brasil.
+
+## Como instalar?
+
+Se você usar o `uv`:
+
+```sh
+uv add bb_api
+```
+
+Se você usar o `pip`:
+
+```sh
+pip install bb_api
+```
+
+## Funcionalidades
+
+- Lê os parâmetros `app_key`, `client_id` e `client_secret` das variáveis de
+  ambiente `BB_API_APP_KEY`, `BB_API_CLIENT_ID` e `BB_API_CLIENT_SECRET`,
+  respectivamente, caso não sejam passadas na instanciação das classes
+- Gera o token de acesso automaticamente, gerando um novo a cada 10 minutos,
+  tempo de expiração do token definido pelo Banco do Brasil
+- Separa operaçãos disponíveis aos órgãos de repasse e de controle em classes
+  separadas, mantendo as operações comuns aos dois
+- Retorna os resultados das chamadas às APIS em formato de `DataFrame` do
+  [`pandas`][pandas]
+- Aceita parâmetros em múltiplos formatos, como:
+  - CNPJ e CEP podem estar pontuados ou não
+  - Datas podem estar em formato `str`, `date` ou `datetime`
+
+## Referências
+
+Os documentos utilizados de referência para criação dessa API foram:
+
+- [Portal Developers BB]
+- [Documentação Swagger API BB]
+
+[pandas]: https://pandas.pydata.org/
+[Portal Developers BB]: https://apoio.developers.bb.com.br/referency/post/641877548600960012b32cd6
+[Documentação Swagger API BB]: https://api.bb.com.br/accountability/v3/swagger

bb_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+bb_api/__init__.py,sha256=K-QN7K2yzWDIJMSXf5RvQmigYv2TyvYJrXQdEyGcYpY,520
+bb_api/accountability.py,sha256=8acRN30vmWydcPf5L7lctnQsq0bAA8QMTrKNap6CM2o,74988
+bb_api/common.py,sha256=A1kOGKHJuF79ZZyDDAdFcctEfzr11Bh0l9KyuFXgeP0,2265
+bb_api/gestao_agil.py,sha256=sEMlVH8CB8A1kkGbAGfy9wF374Jn5FT2jny8Vg9-bAE,8955
+bb_api-0.1.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+bb_api-0.1.0.dist-info/METADATA,sha256=rgAjG_QBO4gy6gAwWTXZ1-glNyKC0X1xM0AjlWTjts8,1588
+bb_api-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bb_api-0.1.0.dist-info/top_level.txt,sha256=ZMdA0Lx6osrxQHw-iizi8tXTIofFtsg_qPApwC2xPOM,7
+bb_api-0.1.0.dist-info/RECORD,,

bb_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+