brbank 0.0.1__tar.gz

brbank-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest --cov=brbank

brbank-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: publish
+on:
+  release:
+    types: [published]
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

brbank-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.coverage
+dist/
+*.pem
+*.pfx
+*.crt
+*.key

brbank-0.0.1/CLAUDE.md

@@ -0,0 +1,28 @@
+# CLAUDE.md
+
+Biblioteca `brbank` (cobranca bancaria unificada). Nao importar nada do Odoo.
+
+```bash
+uv sync                          # instala (inclui o entry point brbank.adapters)
+uv run pytest                    # testes (sem rede: httpx.MockTransport)
+uv run pytest --cov=brbank       # cobertura (meta 80% no core)
+uv run ruff check .              # lint
+```
+
+## Layout
+
+- `src/brbank/`: `modelos` (B1), `adapter` (B2), `capacidades` (B3), `registro` (B4),
+  `transporte` (B5), `auth` (B6), `envelope` (B7), `erros` (B8), `status` (B9),
+  `orquestrador` (B10), `mascara` (LGPD), `documento` (CPF/CNPJ).
+- `src/brbank/adapters/<banco>.py`: um adapter por banco, registrado em
+  `[project.entry-points."brbank.adapters"]`.
+- `tests/test_contrato.py`: suite comum registrar -> consultar -> baixar; adapter
+  novo entra em `FABRICAS` com um servidor falso.
+
+## Regras
+
+- Dinheiro sempre `Decimal`. Nunca logar nem guardar PII/segredo em claro: usar `mascarar`.
+- CNPJ alfanumerico: A-Z sem letras vedadas, DV por ASCII-48.
+- Adapter portado de modulo Odoo: citar a origem no docstring e listar divergencias.
+- Texto sem travessao nem caractere tipografico (so teclado QWERTY). Commits:
+  `[ADD]`/`[FIX]` em portugues, sem Co-Authored-By, trailer `Assisted-by: Claude`.

brbank-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KMEE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brbank-0.0.1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: brbank
+Version: 0.0.1
+Summary: Cobranca bancaria unificada (boleto e Pix) para bancos brasileiros, independente do Odoo
+Project-URL: Homepage, https://github.com/kmee/brbank
+Project-URL: Issues, https://github.com/kmee/brbank/issues
+Author-email: KMEE <info@kmee.com.br>
+License: MIT
+License-File: LICENSE
+Keywords: asyncio,banco,boleto,brasil,cobranca,pix
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=50.0.2
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: pydantic>=2.6
+Description-Content-Type: text/markdown
+
+# brbank
+
+Biblioteca Python assincrona para emitir e acompanhar boletos e cobrancas Pix em
+bancos brasileiros por uma interface unica. Nao importa nada do Odoo: o modulo
+`l10n_br_payment_boleto` e uma das faces possiveis.
+
+Licenca MIT. Python 3.11+. **Alfa:** nenhum adapter foi validado em sandbox de
+banco (`validado_sandbox = False`); o contrato de cada banco vem da documentacao
+publica e de fontes de terceiros, com as duvidas em `docs/<banco>-duvidas.md`.
+Estado: primeira fatia (modelo canonico, contrato
+de adapter, transporte, autenticacao, orquestrador e os adapters da tabela abaixo).
+
+## Bancos suportados
+
+Todos os adapters passam pela mesma suite de contrato (registrar, consultar, baixar) contra um
+servidor falso. "Origem" diz de onde veio o contrato: **Odoo** = portado de um modulo que ja roda
+em producao (o adapter da biblioteca ainda nao rodou contra o banco), **ACBr** = levantado por leitura
+do ACBr, usado so como documentacao, e de fontes de terceiros.
+
+| Banco | Adapter (entry point) | Produto | Capacidades declaradas | Origem |
+| --- | --- | --- | --- | --- |
+| Inter (077) | `inter` | Cobranca v3, boleto hibrido | hibrido, so hibrido, baixa, PDF, webhook | Odoo |
+| PinBank | `pinbank` | Boleto, envelope AES-CBC | baixa | Odoo |
+| Sicoob (756) | `sicoob` | Cobranca v3, boleto hibrido | hibrido, alteracao, baixa | ACBr |
+| Sicredi (748) | `sicredi` | Cobranca v2 | hibrido, alteracao, baixa, webhook | ACBr |
+| Banco do Brasil (001) | `bb` | Cobranca v2 | alteracao, baixa | ACBr |
+
+Pix (BACEN `/cob`, `/cobv`, `/webhook`) por um adapter generico, `pix_bacen`, com um perfil por PSP
+(host, escopos, headers e quirks): Inter, Banco do Brasil, Sicoob, Sicredi, Itau, Bradesco,
+Santander e Efi. Capacidades: Pix cob e cobv, webhook, baixa.
+
+Fora desta lista por enquanto: BNB (sem referencia de Pix confiavel), Caixa, Safra, Banrisul,
+Unicred, BTG e C6 (planejados), gateways como Mercado Pago, PagBank e Stone (sob demanda) e a
+variante ECOMM do Sicredi. Banco novo = um adapter com `BankAdapter` e um entry point em
+`brbank.adapters`; veja `docs/` para o que cada banco ainda deixa em aberto.
+
+**Nenhum adapter da biblioteca foi validado em sandbox.** Sicoob, Sicredi, Banco do Brasil e os
+perfis Pix trazem `validado_sandbox = False` no codigo e so passam a `True` depois de rodar contra o
+ambiente real do banco. Inter e PinBank herdam a logica de modulos Odoo em producao, mas o adapter
+da biblioteca tambem ainda nao rodou contra o banco.
+
+## Uso
+
+```python
+from brbank import Orquestrador
+from brbank.adapters.inter import InterAdapter, InterConfig
+
+config = InterConfig(
+    conta="matriz",
+    client_id="...",
+    client_secret="...",
+    conta_corrente="123456",
+    ambiente="sandbox",
+    certificado_pem=cert_bytes,
+    chave_pem=chave_bytes,  # vindos do cofre
+)
+adapter = InterAdapter(config)
+orquestrador = Orquestrador(adapter, concorrencia=10)
+
+registrado = await orquestrador.emitir(titulo)  # idempotente por chave
+resultados = await orquestrador.emitir_em_varios(lote)  # falha isolada por titulo
+```
+
+Um banco novo e um pacote que registra o adapter no entry point `brbank.adapters`:
+
+```toml
+[project.entry-points."brbank.adapters"]
+inter = "brbank.adapters.inter:InterAdapter"
+pinbank = "brbank.adapters.pinbank:PinbankAdapter"
+sicoob = "brbank.adapters.sicoob:SicoobAdapter"
+
+sicredi = "brbank.adapters.sicredi:SicrediAdapter"
+
+pix_bacen = "brbank.adapters.pix_bacen:PixBacenAdapter"
+```
+
+O `PinbankAdapter` usa OAuth2 `password` e payload cifrado AES-CBC (`EnvelopeAesCbc`),
+registra, consulta e baixa por `NossoNumero`, e nao tem webhook nem PDF. Contrato em
+aberto: `docs/pinbank-duvidas.md`.
+
+O `SicoobAdapter` (Cobranca Bancaria v3, boleto hibrido) usa OAuth2 `client_credentials`
+sem `client_secret` (a identidade e o mTLS), header `client_id`, id do titulo = nosso
+numero, registra, consulta, baixa e envia instrucao (prorrogacao, abatimento, protesto).
+Sem PDF e sem webhook declarados. **`validado_sandbox = False`**: contrato montado de
+documentacao de terceiros, nunca executado contra o Sicoob. Duvidas: `docs/sicoob-duvidas.md`.
+
+O `BancoDoBrasilAdapter` (`bb`, API Cobranca v2, convenio de 6 ou 7 digitos) usa OAuth2
+`client_credentials` e a chave `gw-dev-app-key` em query param; registra, consulta, baixa,
+prorroga e abate, sem webhook nem PDF. Nasce com `validado_sandbox = False`: ver
+`docs/bb-duvidas.md`.
+
+O `SicrediAdapter` (API de Cobranca v2, OAuth2 `password`) registra, consulta, baixa e
+altera (prorrogacao e abatimento); webhook sem assinatura exige reconsulta. Nasce com
+`validado_sandbox = False`; contrato em aberto: `docs/sicredi-duvidas.md`.
+
+O `PixBacenAdapter` fala a API Pix do BACEN (`/cob`, `/cobv`, `/webhook`, devolucao) e
+muda de banco por `PerfilPsp`: `inter`, `bb`, `sicoob`, `sicredi`, `itau`, `bradesco`,
+`santander` e `efi` (BNB sem perfil). Todos com `validado_sandbox = False` ate rodar no
+sandbox. O `txid` vem da chave de idempotencia, o copia-e-cola e o `txid` chegam em
+`TituloRegistrado`, e `CONCLUIDA` sem Pix na consulta nao liquida. Duvidas e quirks:
+`docs/pix-duvidas.md`.
+
+```python
+config = PixBacenConfig(
+    perfil="sicoob",
+    conta="matriz",
+    chave_pix="...",
+    client_id="...",
+    ambiente="producao",
+    certificado_pem=cert,
+    chave_pem=chave,
+)
+adapter = PixBacenAdapter(config)
+```
+
+`brbank.criar_adapter("inter", config)` resolve pelo nome e
+`adapter.suporta(Capacidade.PDF)` consulta as capacidades em runtime.
+
+## Regras
+
+- Valores em `Decimal` (float e recusado). Percentuais em unidade de percentual.
+- Nome, documento e endereco ficam fora do `repr`; log, erro e resposta bruta
+  passam por `brbank.mascara.mascarar`.
+- Retry so para 429, 5xx e erro de transporte. Status desconhecido no banco
+  levanta erro, nunca vira "pago".
+- Webhook gera `EventoCanonico` e nao confirma nada: reconsulte antes de liquidar.

brbank-0.0.1/README.md

@@ -0,0 +1,126 @@
+# brbank
+
+Biblioteca Python assincrona para emitir e acompanhar boletos e cobrancas Pix em
+bancos brasileiros por uma interface unica. Nao importa nada do Odoo: o modulo
+`l10n_br_payment_boleto` e uma das faces possiveis.
+
+Licenca MIT. Python 3.11+. **Alfa:** nenhum adapter foi validado em sandbox de
+banco (`validado_sandbox = False`); o contrato de cada banco vem da documentacao
+publica e de fontes de terceiros, com as duvidas em `docs/<banco>-duvidas.md`.
+Estado: primeira fatia (modelo canonico, contrato
+de adapter, transporte, autenticacao, orquestrador e os adapters da tabela abaixo).
+
+## Bancos suportados
+
+Todos os adapters passam pela mesma suite de contrato (registrar, consultar, baixar) contra um
+servidor falso. "Origem" diz de onde veio o contrato: **Odoo** = portado de um modulo que ja roda
+em producao (o adapter da biblioteca ainda nao rodou contra o banco), **ACBr** = levantado por leitura
+do ACBr, usado so como documentacao, e de fontes de terceiros.
+
+| Banco | Adapter (entry point) | Produto | Capacidades declaradas | Origem |
+| --- | --- | --- | --- | --- |
+| Inter (077) | `inter` | Cobranca v3, boleto hibrido | hibrido, so hibrido, baixa, PDF, webhook | Odoo |
+| PinBank | `pinbank` | Boleto, envelope AES-CBC | baixa | Odoo |
+| Sicoob (756) | `sicoob` | Cobranca v3, boleto hibrido | hibrido, alteracao, baixa | ACBr |
+| Sicredi (748) | `sicredi` | Cobranca v2 | hibrido, alteracao, baixa, webhook | ACBr |
+| Banco do Brasil (001) | `bb` | Cobranca v2 | alteracao, baixa | ACBr |
+
+Pix (BACEN `/cob`, `/cobv`, `/webhook`) por um adapter generico, `pix_bacen`, com um perfil por PSP
+(host, escopos, headers e quirks): Inter, Banco do Brasil, Sicoob, Sicredi, Itau, Bradesco,
+Santander e Efi. Capacidades: Pix cob e cobv, webhook, baixa.
+
+Fora desta lista por enquanto: BNB (sem referencia de Pix confiavel), Caixa, Safra, Banrisul,
+Unicred, BTG e C6 (planejados), gateways como Mercado Pago, PagBank e Stone (sob demanda) e a
+variante ECOMM do Sicredi. Banco novo = um adapter com `BankAdapter` e um entry point em
+`brbank.adapters`; veja `docs/` para o que cada banco ainda deixa em aberto.
+
+**Nenhum adapter da biblioteca foi validado em sandbox.** Sicoob, Sicredi, Banco do Brasil e os
+perfis Pix trazem `validado_sandbox = False` no codigo e so passam a `True` depois de rodar contra o
+ambiente real do banco. Inter e PinBank herdam a logica de modulos Odoo em producao, mas o adapter
+da biblioteca tambem ainda nao rodou contra o banco.
+
+## Uso
+
+```python
+from brbank import Orquestrador
+from brbank.adapters.inter import InterAdapter, InterConfig
+
+config = InterConfig(
+    conta="matriz",
+    client_id="...",
+    client_secret="...",
+    conta_corrente="123456",
+    ambiente="sandbox",
+    certificado_pem=cert_bytes,
+    chave_pem=chave_bytes,  # vindos do cofre
+)
+adapter = InterAdapter(config)
+orquestrador = Orquestrador(adapter, concorrencia=10)
+
+registrado = await orquestrador.emitir(titulo)  # idempotente por chave
+resultados = await orquestrador.emitir_em_varios(lote)  # falha isolada por titulo
+```
+
+Um banco novo e um pacote que registra o adapter no entry point `brbank.adapters`:
+
+```toml
+[project.entry-points."brbank.adapters"]
+inter = "brbank.adapters.inter:InterAdapter"
+pinbank = "brbank.adapters.pinbank:PinbankAdapter"
+sicoob = "brbank.adapters.sicoob:SicoobAdapter"
+
+sicredi = "brbank.adapters.sicredi:SicrediAdapter"
+
+pix_bacen = "brbank.adapters.pix_bacen:PixBacenAdapter"
+```
+
+O `PinbankAdapter` usa OAuth2 `password` e payload cifrado AES-CBC (`EnvelopeAesCbc`),
+registra, consulta e baixa por `NossoNumero`, e nao tem webhook nem PDF. Contrato em
+aberto: `docs/pinbank-duvidas.md`.
+
+O `SicoobAdapter` (Cobranca Bancaria v3, boleto hibrido) usa OAuth2 `client_credentials`
+sem `client_secret` (a identidade e o mTLS), header `client_id`, id do titulo = nosso
+numero, registra, consulta, baixa e envia instrucao (prorrogacao, abatimento, protesto).
+Sem PDF e sem webhook declarados. **`validado_sandbox = False`**: contrato montado de
+documentacao de terceiros, nunca executado contra o Sicoob. Duvidas: `docs/sicoob-duvidas.md`.
+
+O `BancoDoBrasilAdapter` (`bb`, API Cobranca v2, convenio de 6 ou 7 digitos) usa OAuth2
+`client_credentials` e a chave `gw-dev-app-key` em query param; registra, consulta, baixa,
+prorroga e abate, sem webhook nem PDF. Nasce com `validado_sandbox = False`: ver
+`docs/bb-duvidas.md`.
+
+O `SicrediAdapter` (API de Cobranca v2, OAuth2 `password`) registra, consulta, baixa e
+altera (prorrogacao e abatimento); webhook sem assinatura exige reconsulta. Nasce com
+`validado_sandbox = False`; contrato em aberto: `docs/sicredi-duvidas.md`.
+
+O `PixBacenAdapter` fala a API Pix do BACEN (`/cob`, `/cobv`, `/webhook`, devolucao) e
+muda de banco por `PerfilPsp`: `inter`, `bb`, `sicoob`, `sicredi`, `itau`, `bradesco`,
+`santander` e `efi` (BNB sem perfil). Todos com `validado_sandbox = False` ate rodar no
+sandbox. O `txid` vem da chave de idempotencia, o copia-e-cola e o `txid` chegam em
+`TituloRegistrado`, e `CONCLUIDA` sem Pix na consulta nao liquida. Duvidas e quirks:
+`docs/pix-duvidas.md`.
+
+```python
+config = PixBacenConfig(
+    perfil="sicoob",
+    conta="matriz",
+    chave_pix="...",
+    client_id="...",
+    ambiente="producao",
+    certificado_pem=cert,
+    chave_pem=chave,
+)
+adapter = PixBacenAdapter(config)
+```
+
+`brbank.criar_adapter("inter", config)` resolve pelo nome e
+`adapter.suporta(Capacidade.PDF)` consulta as capacidades em runtime.
+
+## Regras
+
+- Valores em `Decimal` (float e recusado). Percentuais em unidade de percentual.
+- Nome, documento e endereco ficam fora do `repr`; log, erro e resposta bruta
+  passam por `brbank.mascara.mascarar`.
+- Retry so para 429, 5xx e erro de transporte. Status desconhecido no banco
+  levanta erro, nunca vira "pago".
+- Webhook gera `EventoCanonico` e nao confirma nada: reconsulte antes de liquidar.

brbank-0.0.1/docs/bb-duvidas.md

@@ -0,0 +1,83 @@
+# Banco do Brasil: duvidas em aberto do contrato
+
+Fontes usadas, por ordem de confianca:
+
+1. **Doc oficial (developers.bb.com.br / apoio.developers.bb.com.br):** NAO foi
+   possivel ler. A pagina de referencia carrega por JavaScript e o WebFetch devolveu
+   so "Aguarde...". WebSearch nao trouxe a pagina oficial. Tudo abaixo precisa ser
+   conferido contra ela e contra o sandbox antes de producao.
+2. **Leitura (so como documentacao, sem portar codigo, licenca LGPL) do ACBrBoleto:**
+   `WS/ACBrBoletoW_BancoBrasil_API.pas`, `WS/ACBrBoletoRet_BancoBrasil_API.pas`,
+   `ACBrBancoBrasil.pas` e a secao 3.1 de `Particularidades.html`. Dela vem: URLs,
+   `gw-dev-app-key` em query, paths, nomes de campo do payload e da resposta, datas
+   `DD.MM.YYYY`, composicao do `numeroTituloCliente`, tabela de `codigoEstadoTituloCobranca`,
+   campos de alteracao (PATCH) e o header `x-bb-portal-devx-cnpj-parceiro`.
+3. **Fonte de terceiro (wiki CIGAM, via WebSearch):** escopos
+   `cobrancas.boletos-requisicao` e `cobrancas.boletos-info`.
+
+O adapter nasce com `validado_sandbox = False`.
+
+## Risco do PRD: chave de desenvolvedor e header de parceiro
+
+- `gw-dev-app-key` e **query param** em toda chamada de negocio (nao em header),
+  inclusive no PATCH e no POST de baixa. O adapter a monta em `_caminho`, mantem fora
+  do repr da config e o transporte nunca loga URL.
+- O header `x-bb-portal-devx-cnpj-parceiro` (CNPJ da software house) e opcional
+  (`BBConfig.cnpj_parceiro`). Nao se sabe se o BB passara a exigi-lo.
+
+## Duvidas
+
+1. **Autenticacao do token.** O ACBr usa credenciais no corpo no sandbox e Basic
+   (`client_id:client_secret`) em producao. O adapter replica isso por padrao
+   (`BBConfig.credenciais_no_corpo=None`) e deixa forcar. Confirmar no oficial.
+2. **Escopos.** Fonte de terceiro, nao oficial. O escopo depende dos servicos marcados
+   no app do portal.
+3. **Nosso numero.** `numeroTituloCliente` = "000" + convenio (7 digitos, zeros a
+   esquerda) + nosso numero (10 digitos), pela montagem do ACBr. Para convenio de 6
+   digitos o ACBr aplica a mesma regra na API. O modelo canonico nao tem nosso numero:
+   quem chama passa `BBConfig.gerar_nosso_numero` ou usa `seu_numero` numerico de ate
+   10 digitos. Quem garante a unicidade da sequencia e o chamador. Convenios de 4 e 5
+   digitos (so CNAB) sao recusados.
+4. **Duplicidade.** Nao se sabe qual codigo o BB devolve para `numeroTituloCliente`
+   repetido. So o 409 vira `Duplicado`; a idempotencia real e o cache por
+   `chave_idempotencia` (no processo) e o `Orquestrador`.
+5. **Status do registro.** A resposta traz linha digitavel e codigo de barras, entao o
+   adapter devolve `REGISTRADO` (nao `PENDENTE_REGISTRO`). Nao confirmado.
+6. **Tabela de status.** Mapeados: 1, 2, 3, 4, 5, 8, 9, 13 (REGISTRADO), 6 (LIQUIDADO),
+   7 (BAIXADO), 80 (transitorio, PENDENTE_REGISTRO). **Deliberadamente fora** (levantam
+   `Validacao`): 10 (baixado/pago em cartorio), 11 e 12 (liquidado com protesto ou
+   cartorio), 14 (em liquidacao), 15 e 21 (agendado), 16 (creditado), 17 (pago em
+   cheque), 18 e 19 (pago parcialmente). Sem a doc oficial nao da para saber se cada um
+   e dinheiro recebido; liquidar ou baixar por palpite e pior que recusar. Candidatos a
+   LIQUIDADO apos confirmacao: 11, 12, 16.
+7. **Pagamento parcial.** `indicadorPermissaoRecebimentoParcial` nao e enviado. O
+   modelo canonico nao tem o conceito.
+8. **Data de emissao.** O modelo nao tem `dataEmissao`; o adapter usa a data do dia
+   (`hoje` injetavel). Confirmar se o BB aceita emissao posterior a hoje ou anterior.
+9. **Multa.** O BB exige data de inicio; o adapter usa vencimento + 1 dia (suposicao).
+   Tipo 2 = percentual. Juros: tipo 2 = taxa mensal. Desconto: tipo 2 = percentual ate
+   a data, `dataExpiracao` = vencimento menos `desconto_dias_antes`. Tipos vindos do ACBr.
+10. **Baixa automatica.** `dias_baixa_automatica` e recusado: a equivalencia com
+    `numeroDiasLimiteRecebimento` (prazo de recebimento apos o vencimento) nao e
+    certa. Mensagem: o BB limita a 30 caracteres; acima disso o adapter recusa em vez
+    de truncar em silencio.
+11. **CPF/CNPJ como inteiro.** `numeroInscricao` e `cep` vao como numero (como no
+    ACBr). CNPJ alfanumerico nao cabe: recusado com `Validacao`. Perguntar ao BB.
+12. **Pix no boleto (`indicadorPix`).** Configuravel. Quando "S" a resposta de registro
+    traz `qrCode.emv/txId/url`, que o adapter expoe em `pix_copia_cola` e `txid`. A
+    consulta de detalhe nao traz o Pix (ha `GET /boletos/{id}/pix`, nao implementado), e
+    por isso `HIBRIDO` nao e declarada.
+13. **Baixa.** Resposta com `dataBaixa` e `horarioBaixa`; o adapter devolve `BAIXADO`
+    direto, sem reconsultar.
+14. **Alteracao (PATCH).** Implementados: nova data de vencimento
+    (`indicadorNovaDataVencimento` + `alteracaoData`) e abatimento (incluir se o titulo
+    nao tem `valorAbatimentoTituloCobranca`, alterar se tem; o adapter consulta antes).
+    Cancelar abatimento, desconto, juros, multa, valor nominal, protesto e negativacao
+    existem na API mas ficaram fora (o modelo `Instrucao` nao carrega os dados, ou o
+    efeito nao esta claro). PROTESTO e NEGATIVACAO levantam `NaoSuportado`.
+15. **PDF.** Nao ha endpoint de segunda via no que foi lido; `PDF` nao e declarada.
+16. **Webhook.** Nada no contrato lido. `parse_webhook` levanta `NaoSuportado`.
+17. **Listagem (`GET /boletos` com filtros)** e a API de consulta por periodo ficaram
+    fora da primeira fatia.
+18. **Homologacao.** O ACBr tem um terceiro ambiente (`api.hm.bb.com.br`); o adapter so
+    aceita `sandbox` e `producao`.

brbank-0.0.1/docs/pinbank-duvidas.md

@@ -0,0 +1,40 @@
+# PinBank: duvidas em aberto do contrato
+
+Fonte unica usada: modulo Odoo `l10n_br_payment_boleto_pinbank` (kmee-odoo-addons,
+branch 16.0). Nao ha documentacao oficial da API no repositorio. O que o modulo nao
+esclarece ficou fora do adapter ou recusado com `Validacao`, em vez de inventado.
+
+1. **Unidade de Juros e Multa.** O modulo envia `{"Valor": int(boleto_interest * 10000)}`
+   e `int(boleto_penalty * 10000)`; o vetor de teste usa `Valor: 100`. Nao se sabe se e
+   centesimos de percentual, fracao x 10000, nem se juros e ao dia ou ao mes. O adapter
+   recusa titulo com multa, juros, desconto, abatimento ou baixa automatica.
+2. **Desconto, abatimento e baixa automatica.** O modulo nao envia. Mesmo tratamento.
+3. **Endereco do sacado.** O modulo envia so `street_name` em `Endereco`; numero e
+   complemento nao vao em campo algum. O adapter segue o modulo (so o logradouro).
+4. **CPF/CNPJ e CEP como inteiros.** O modulo envia `int(...)`, o que descarta zeros a
+   esquerda (o vetor mostra `Cep: 8473002` na ida e `"08473002"` na volta). O adapter
+   segue o modulo. CNPJ alfanumerico nao cabe em inteiro: e recusado com `Validacao`.
+   Confirmar com o PinBank se aceitam string e como tratarao o CNPJ alfanumerico.
+5. **Idempotencia no banco.** O modulo nao manda identificador do cliente. A resposta
+   traz `IdentificadorCliente` (nulo no vetor), talvez aceito na geracao. Hoje a garantia
+   contra boleto em dobro e do adapter (cache e lock por `chave_idempotencia`, no
+   processo) e do `Orquestrador` (repositorio de chaves, entre processos).
+6. **PDF.** `RetornarBase64` devolve o PDF so na geracao; nao ha endpoint de segunda via
+   no modulo e a consulta nao traz `Base64`. O adapter nao declara `PDF`. O PDF recebido
+   na geracao fica em `resposta_bruta` mascarado ("***"). Falta um campo no modelo
+   canonico para entrega-lo (decisao de produto) ou confirmar endpoint de segunda via.
+7. **Webhook.** O modulo so faz polling (cron de consulta). Sem contrato: `parse_webhook`
+   levanta `NaoSuportado` e `WEBHOOK` nao e declarada.
+8. **Resposta da baixa.** O modulo ignora o corpo da baixa e reconsulta. O adapter faz
+   igual e devolve o estado consultado, que pode ainda nao ser `BAIXADO`.
+9. **Status.** Mapa extraido do modulo: PENDENTE, REGISTRADO, LIQUIDADO, BAIXA. Se o
+   banco tiver outros (vencido, protestado, rejeitado), o adapter levanta `Validacao`
+   (nunca assume "pago").
+10. **Expiracao do token.** O campo e `expire_in` (sem "s"); o autenticador aceita os dois.
+    Sem escopo OAuth: o cache e por (conta, sem escopo).
+11. **Chave AES = senha do usuario**, IV zero, como no modulo. O IV fixo torna o cifrado
+    deterministico: a protecao real e o TLS.
+12. **Erro HTTP com corpo cifrado ou nao.** O modulo le `Message` em claro nos erros;
+    o adapter nao decifra respostas >= 400 e as repassa mascaradas.
+13. **Valor do boleto como `Valor` em centavos e `ValorPago` em centavos** (vetor:
+    `Valor: 25875`). `ValorPago` so e lido quando LIQUIDADO.

brbank-0.0.1/docs/pix-duvidas.md

@@ -0,0 +1,82 @@
+# Pix BACEN generico: duvidas em aberto e quirks
+
+Fonte do contrato: OpenAPI oficial da API Pix do BACEN (/cob, /cobv, /webhook,
+/pix/{e2eid}/devolucao), conhecido do padrao publico. O comportamento por PSP
+(host, URL do token, escopos, headers, quirks) foi lido nos fontes do ACBr
+(`ACBrPIXCD`, licenca LGPL) como documentacao, sem portar codigo. Nenhum perfil
+foi testado contra sandbox real: todos nascem com `validado_sandbox = False`.
+O que a leitura nao esclarece ficou de fora ou recusado, nao inventado.
+
+## Perfis
+
+| Perfil | Auth | Escopo | mTLS | Quirks aplicados |
+|---|---|---|---|---|
+| inter | form (id+segredo) | sim | sim | nenhum |
+| bb (API v2) | Basic | sim | prod | header `x-bb-portal-devx-cnpj-parceiro`, query `gw-dev-app-key`, alias `textoImagemQRcode` |
+| sicoob | so `client_id` (sandbox: token fixo do portal) | sim | prod | header `client_id`, alias `brcode` -> `pixCopiaECola` |
+| sicredi | Basic | sim | sim | nenhum |
+| itau | form (id+segredo) | nao | prod | header `x-correlationID` (UUID por chamada) |
+| bradesco | Basic, HTTP/1.1 | nao | sim | nenhum |
+| santander | form, `?grant_type` na URL | nao | prod | sandbox cria por POST, baixa (PATCH) em `/api/v2` na producao |
+| efi (GerenciaNet) | Basic + corpo JSON, HTTP/1.1 | nao | sim | header opcional `x-partner-token` |
+| bnb | sem perfil | | | ver abaixo |
+
+## Duvidas
+
+1. **BNB sem perfil.** O ACBr nao tem PSP do Banco do Nordeste. `obter_perfil("bnb")`
+   levanta `Validacao`. Falta documentacao do portal do BNB (host, token, escopos).
+2. **Escopos.** O ACBr pede por padrao cob/cobv/pix/webhook (read e write). Nao ha
+   evidencia de qual conjunto cada banco aceita; se o banco recusar um escopo, o
+   token falha. Ajustar `escopos` no perfil quando o sandbox responder. Itau, Bradesco,
+   Santander e Efi nao mandam escopo (como no ACBr).
+3. **Idempotencia do `txid`.** O `txid` sai do SHA-256 de `conta|chave_idempotencia`
+   (32 hex, dentro de 26-35). A OpenAPI nao diz qual HTTP um PSP devolve para PUT em
+   txid existente; o adapter so converte em consulta o 409 (`Duplicado`). Se algum
+   banco devolve 400 ou 422, o titulo falha como `Validacao` e o `Orquestrador` (que
+   guarda a chave) evita a repeticao. Confirmar por banco.
+4. **PUT versus POST.** O adapter sempre cria por `PUT /cob(v)/{txid}`. O ACBr converte
+   POST em PUT para BB v1 e Santander, e o sandbox do Santander so aceita POST (perfil
+   `metodo_criar_sandbox`). `POST /cob` com txid gerado pelo banco nao e usado.
+5. **BB API v1.** So a v2 tem perfil. A v1 (`api.bb.com.br/pix/v1`) tem `/cobqrcode`
+   no sandbox e delimitador `/` antes da query; nao implementado. Confirmar qual
+   versao usar.
+6. **Santander pre-producao e sandbox.** Existe host de pre-producao
+   (`trust-pix-h.santander.com.br`), sem perfil. O sandbox devolve JSON fora do padrao
+   (lista `cobs[0]`/`pix[0]`); o ACBr corrige, o adapter nao.
+7. **Itau sandbox.** Exige o header `x-sandbox-token` com o token obtido; o autenticador
+   atual nao expoe o token ao adapter. Nao implementado. O fluxo de certificado
+   (CSR/renovacao em `/seguranca/v1/certificado`) tambem fica fora.
+8. **Sicoob em producao.** O ACBr manda so `client_id`, sem segredo, e a identidade vem
+   do mTLS. Confirmar que nao ha `client_secret`.
+9. **HTTP/1.1.** O ACBr forca 1.1 so na chamada de token de Bradesco e Efi. Aqui o
+   cliente inteiro desses perfis usa 1.1 (`Transporte(http2=False)`), mais simples e
+   mais conservador. Confirmar se so o token precisa.
+10. **Webhook sem assinatura.** O BACEN protege o callback por mTLS do PSP, nao por HMAC.
+    `parse_webhook` nao autentica nada: o receptor precisa validar o certificado do PSP
+    (fora da lib) e reconsultar antes de liquidar. A Efi documenta um header para pular
+    a checagem de mTLS no cadastro do webhook (`x-skip-mtls-checking`), do conhecimento
+    geral e nao da referencia: nao implementado.
+11. **Webhook sem `txid`.** Pix de QR estatico chega sem `txid`; o adapter ignora (sem
+    titulo para baixar). Se o produto quiser conciliar Pix avulso, falta um evento
+    canonico proprio. Devolucoes dentro do corpo (`devolucoes`) tambem sao ignoradas.
+12. **Valor pago parcial e devolucao.** `valor_pago` e a soma de `pix[].valor` da
+    consulta, sem descontar devolucoes. Cobranca com `modalidadeAlteracao` nao e
+    emitida (valor fixo), entao pagamento parcial nao e esperado.
+13. **CNPJ alfanumerico.** O adapter envia `cnpj` com o valor normalizado (A-Z e digitos).
+    Nao se sabe quais PSPs ja aceitam letras no campo `devedor.cnpj` (o schema antigo
+    exigia 14 digitos).
+14. **Endereco do devedor.** Em `cobv` o adapter manda logradouro (com numero), cidade,
+    UF e CEP quando o `Pessoa` tem endereco. Alguns PSPs podem exigir todos os campos;
+    nao e validado localmente.
+15. **Mapeamento de encargos para `cobv`.** Multa = modalidade 2 (percentual); juros =
+    modalidade 3 (percentual ao mes, dias corridos); abatimento = modalidade 1 (valor
+    fixo); desconto = modalidade 2 (percentual ate a data, `vencimento - dias_antes`).
+    O `valorPerc` do abatimento e um valor em reais, nao percentual, apesar do nome do
+    campo no BACEN. Juros e multa em outras modalidades (dia util, ao dia) ficam fora.
+16. **`REMOVIDA_PELO_PSP`.** Mapeada para `BAIXADO`. Pode ser expiracao; se o produto
+    quiser distinguir, falta um status canonico.
+17. **`cob` imediata.** Recusa multa, juros, desconto e abatimento; a validade e
+    `expiracao_s` (padrao 86400), nao o vencimento do `Titulo`.
+18. **Fora do escopo desta entrega:** consulta de Pix por `e2eid` e por periodo, listagem
+    de cobrancas, lote `cobv`, `payloadlocation`, recorrencia (`rec`, `cobr`), revisao
+    de valor (PATCH com `valor`) e `enviar_instrucao`.

brbank-0.0.1/docs/sicoob-duvidas.md

@@ -0,0 +1,76 @@
+# Sicoob (756) API de Cobranca v3: duvidas em aberto
+
+`SicoobAdapter.validado_sandbox = False`. Nada foi executado contra o Sicoob.
+
+## Fontes
+
+- Referencia de comportamento LIDA (LGPL, nenhum codigo portado, usada so como
+  documentacao de endpoints, campos e quirks): ACBr, `ACBrBoletoW_Sicoob_V3.pas`,
+  `ACBrBoletoRet_Sicoob_V3.pas`, `ACBrBancoSicoob.pas` e `Particularidades`.
+- Documentacao oficial: o portal `developers.sicoob.com.br` nao entrega a especificacao
+  sem login (WebFetch devolveu so o titulo da pagina). Nao foi possivel conferir o swagger.
+- Terceiros lidos: thread do forum ACBr sobre a migracao para a v3 (URLs, mudancas de
+  formato) e README do `mangati/sicoob-sdk` (escopo `boletos_inclusao`, `pdfBoleto`).
+
+Antes de usar em producao: obter o swagger v3 e rodar a suite contra o sandbox
+(token fixo do sandbox fica no portal, entra em `SicoobConfig.token_sandbox`).
+
+## Duvidas
+
+1. **Corpo do POST /boletos: objeto ou lista?** O ACBr monta um objeto; o swagger v3 pode
+   exigir lista. O adapter envia objeto e aceita `resultado` como objeto ou lista (e
+   `resultado.boleto` aninhado). Confirmar.
+2. **Escopos.** So `boletos_inclusao` tem o nome confirmado em fonte de terceiros.
+   `boletos_consulta` e `boletos_alteracao` sao suposicao, por isso ficam em
+   `SicoobConfig.escopos` (chaves `incluir`, `consultar`, `alterar`).
+3. **Token sem `client_secret`.** O ACBr envia so `client_id`, `scope`, `grant_type`
+   (a autenticacao e o certificado mTLS, que tambem vale na chamada de token). Seguido.
+   Token expira em ~300s segundo o SDK de terceiros; o cache usa `expires_in` da resposta.
+4. **Nosso numero como id.** Consulta, baixa e alteracao usam `nossoNumero` na URL. O
+   ACBr calcula e anexa o digito verificador antes de montar a URL; nao se sabe se o
+   `nossoNumero` devolvido no registro ja o inclui. O adapter usa o valor devolvido como
+   veio. Confirmar.
+5. **Consulta.** `GET /boletos?numeroCliente&codigoModalidade&nossoNumero`; 204 (sem
+   conteudo) vira `Validacao`. Campo de situacao: `situacaoBoleto` com textos como
+   "Em Aberto", "Liquidado", "Baixado", "CANCELADO". Lista completa desconhecida.
+6. **Status.** Mapeados so EM ABERTO, LIQUIDADO, BAIXADO, CANCELADO. `VENCIDO` e
+   `EXPIRADO` existem como constantes no ACBr sem uso: ficam fora (viram `Validacao`)
+   ate haver contrato. Um boleto vencido e em aberto ainda e cobravel? Confirmar.
+7. **Valor e data do pagamento.** Nao ha campo numerico: o valor vem de texto em
+   `listaHistorico[tipoHistorico=6].descricaoHistorico` apos "R$". O adapter interpreta
+   formato pt-BR e, se falhar, devolve `valor_pago=None`. Formato real desconhecido.
+8. **PDF.** Fora: o ACBr envia `gerarPdf=false` e so le `pdfBoleto` no registro. Existe
+   provavelmente um endpoint de segunda via, nao confirmado. `PDF` nao e declarada.
+9. **Webhook.** Nao ha contrato conhecido para boleto. `WEBHOOK` nao declarada,
+   `parse_webhook` levanta `NaoSuportado`. O ACBr usa polling por movimentacao.
+10. **Movimentacao (fora do escopo).** `POST /boletos/movimentacoes`, consulta da
+    solicitacao e download de arquivo zip em base64 (siglas ENTR, PROR, AVENC, VENC,
+    LIQUI, BAIX; janela de 2 dias). Util para conciliar em lote; nao implementado.
+11. **Alteracao.** `PATCH /boletos/{nn}` com `prorrogacaoVencimento`, `abatimento` (e,
+    na referencia, `desconto`, `jurosMora`, `multa`, `seuNumero`); protesto em
+    `POST /boletos/{nn}/protestos`; negativacao em `/negativacoes` com verbos variados
+    (nao implementada). O adapter cobre PRORROGACAO, ABATIMENTO, PROTESTO e BAIXA e devolve
+    o estado reconsultado (a API nao devolve dados na alteracao).
+12. **Desconto.** O modelo canonico traz percentual + dias antes; foi mapeado para
+    `tipoDesconto=2` (percentual ate a data informada), data = vencimento - dias. A
+    alternativa `5` (percentual por antecipacao em dias corridos) pode ser mais fiel.
+13. **Multa e juros.** Percentual de multa = `tipoMulta 2`; juros mensal = `tipoJurosMora 2`.
+    Data de inicio (`dataMulta`, `dataJurosMora`) = vencimento + 1 dia, escolha do adapter
+    (o ACBr reaproveita a data de juros). Sem encargo: `tipoMulta 0`, `tipoJurosMora 3`.
+14. **Campos obrigatorios nao deduzidos.** `codigoEspecieDocumento` (sem padrao: vem da
+    config, tabela do banco), `codigoModalidade` (padrao 1, simples com registro),
+    `numeroParcela` (1), `aceite` (false), emissao e distribuicao pelo banco
+    (`banco_emite_e_distribui`). `dataEmissao` e a data do dia, injetavel nos testes.
+15. **Baixa automatica por dias** nao tem campo conhecido: o titulo com
+    `dias_baixa_automatica` e recusado. Protesto e negativacao no registro (`codigoProtesto`,
+    `numeroDiasProtesto`, `codigoNegativacao`) nao existem no modelo canonico.
+16. **CPF/CNPJ.** Enviados sem mascara; se a API aceita CNPJ alfanumerico e
+    desconhecido. CEP so digitos. Endereco = logradouro + numero (a API nao tem campo
+    separado na referencia); complemento nao e enviado.
+17. **Cota.** O ACBr limita a 2 envios por segundo; adotado como padrao
+    (`requisicoes_por_segundo=2.0`). Limite real desconhecido.
+18. **Erros.** O corpo de erro traz `mensagens[{codigo, mensagem}]` segundo a referencia;
+    o adapter nao interpreta (o transporte mascara e repassa). Duplicidade nao
+    mapeada para `Duplicado` por falta de codigo conhecido.
+19. **Hibrido.** `HIBRIDO` e declarada fixa, mas depende de `cadastrar_pix=True`
+    (`codigoCadastrarPIX=1`), que exige Pix habilitado na cooperativa. O QR vem em `qrCode`.