--- name: integrar-api-boletos-ringer description: >- Integra um banco, instituição de pagamento ou lotérica com a API do Boleto Ringer da Conta Comigo Digital (digitalbank 2.0): login OAuth2, cadastro de pessoa pagadora, webhook de monitoramento, consulta de boletos, PDF da fatura e confirmação de pagamento. Use quando aparecer boleto ringer, Boleto Ringer, Conta Comigo Digital, hub conta comigo, digitalbank 2.0, RINGER_0, RINGER_1, RINGER_2, RINGER_3, RINGER_4, boletostoexpire, paidboletos, webhook de boleto, secret_key de webhook, HMAC X-Signature, ou erros como "Invalid X-Signature", "invalid access token", "boleto has already been paid". --- # Integrar com a API do Boleto Ringer (digitalbank 2.0) O Boleto Ringer entrega ao banco os boletos de consumo (água, luz, gás, telefonia, impostos) dos seus clientes, para o banco exibi-los no app, no ATM ou na agência. ## Regras que valem antes de qualquer código 1. **Não fabrique contrato.** Só use endpoints, headers e campos que existam nas páginas indexadas por `https://conta-comigo-b2b.readme.io/llms.txt`. Se você não encontrou o endpoint na documentação, ele não existe para esta integração — pergunte, não invente. Rota que você encontrar fora da doc **não é contrato público**. 2. **A documentação oficial é a fonte da verdade**, acima deste arquivo e acima dos exemplos. Quando faltar detalhe de contrato, busque o `llms.txt`, escolha a página e baixe o markdown cru trocando a URL por `.../reference/.md`. 3. **Sandbox primeiro.** Consulta em produção é evento de entrega faturável. Os exemplos recusam o host de produção sem `CCD_ALLOW_PRODUCTION=1`. Não remova essa trava. 4. **Nenhum segredo no código.** Credenciais só por variável de ambiente (ver `env.example`). 5. **Só a versão `2.0`.** Nada de versões legadas. ## Quando ler o `REFERENCE.md` `REFERENCE.md` (neste mesmo diretório) é o contrato completo, com link para a página de origem de cada afirmação. Vá até ele — não adivinhe — quando precisar de: | Dúvida | Seção | | ------ | ----- | | host de sandbox/produção, prefixo de path | §1 | | como fazer login, o que vai no corpo, vida do token | §2 | | headers HMAC, string canônica, vetor de teste, tolerância | §3 | | allowlist de IP, mTLS, VPN — as outras camadas opcionais | §3.8 | | qual versão usar | §4 | | a lista fechada das 13 rotas, com método e ringer | §5 | | formato do documento (CNPJ é alfanumérico) | §5.3 | | o que significa um `error_code` e o que fazer | §6 | | a doc parece se contradizer | §7 | Se a dúvida não estiver lá, vá ao `llms.txt`. Nunca preencha a lacuna por inferência. ## Passo 0 — Autenticação (pré-requisito de tudo) `POST /o/token/` — OAuth2 `client_credentials` (só `client_id` e `client_secret`), resposta com `access_token` válido por 900 s. Detalhes em `REFERENCE.md` §2. Todo passo abaixo leva `Authorization: Bearer `. Se a sua instituição tem HMAC habilitado, leva **também** os três headers assinados (`REFERENCE.md` §3) — o HMAC soma ao OAuth, não o substitui. ## O fluxo em 5 etapas Execute nesta ordem. Cada etapa depende da anterior. ### 1. Cadastrar a pessoa pagadora (RINGER_1) ``` POST /digitalbank/2.0/clients/ ``` Exige opt-in do titular (LGPD) antes do cadastro. HTTP 409 com `error_code` 1101 (`CPF/CNPJ already registered`) é **sucesso idempotente**: siga para a etapa 2. ### 2. Registrar o webhook de monitoramento (RINGER_0) ``` POST /digitalbank/2.0/monitor/webhooks/ ``` A resposta traz `webhook_id` e `secret_key`. Guarde a `secret_key`: ela chega no header de toda notificação e você **precisa** validá-la sempre — inclusive quando o HMAC está ativo (`REFERENCE.md` §3.7). É por este webhook que você descobre que existe boleto novo. ### 3. Consultar o boleto (RINGER_2) — dois caminhos válidos A escolha depende da implementação do banco; a doc suporta os dois e a skill não impõe um: ``` GET /digitalbank/2.0/clients/{cpf_cnpj}/boletostoexpire/ GET /digitalbank/2.0/clients/{cpf_cnpj}/boletos/{boleto_id}/ ``` - **Lista de boletos a vencer** — quando o banco quer todos os boletos abertos do documento, para montar uma tela de "contas a pagar". É o caminho de descoberta: devolve os `boleto_id`. - **Boleto individual** — quando o banco já tem o `boleto_id`, que chega no `boleto_preview.boleto_id` da própria notificação (etapa 2). Dispensa a listagem. Use **apenas** `boleto_id` que veio da API — da lista ou da notificação. Lista vazia significa "sem boleto disponível": pare e peça massa de teste ao suporte. Nunca invente um `boleto_id`. ### 4. Obter o PDF da fatura (RINGER_3) ``` GET /digitalbank/2.0/clients/{cpf_cnpj}/boletos/{boleto_id}/invoice/ ``` Se responder 200 com `fatura_pdf_url` vazio, reporte o PDF como indisponível e **siga** para a etapa 5 — a fatura é conveniência, não pré-requisito do pagamento. ### 5. Confirmar o pagamento (RINGER_4) ``` POST /digitalbank/2.0/boletos/payment/ ``` Tratamento obrigatório: 409 / 1501 (`boleto has already been paid`) é estado final aceitável — siga; 400 / 1503 aborta citando o campo `payment_date`. ### Conferência ``` GET /digitalbank/2.0/clients/{cpf_cnpj}/boleto/{boleto_id}/history/ ``` Mostra a linha do tempo do boleto (`pending → paid`) e fecha o ciclo. Note o `boleto` no singular nesta rota (`REFERENCE.md` §7.6). ## Erros que você vai encontrar Não adivinhe a causa: o `error_code` e a mensagem estão mapeados em `REFERENCE.md` §6. Os dois reflexos que valem memorizar: - **403 / 1002** (`invalid access token`): renove o token **uma vez** e repita a chamada; segunda falha é erro real. - **`Invalid X-Signature`**: em quase todo caso o `PATH` canônico foi montado sem o prefixo `/digitalbank`, ou o corpo foi re-serializado entre o hash e o envio (`REFERENCE.md` §3.3 e §3.4). ## Exemplos executáveis Mesma decomposição nas quatro linguagens, mesmos nomes de identificador. Copie e adapte: | Responsabilidade | Python | JavaScript | PHP | Java | | ---------------- | ------ | ---------- | --- | ---- | | Login e ciclo do token | `examples/python/auth.py` | `examples/javascript/auth.mjs` | `examples/php/auth.php` | `examples/java/.../CcdAuthClient.java` | | Headers HMAC | `hmac_signer.py` | `hmac_signer.mjs` | `hmac_signer.php` | `HmacSigner.java` | | Validar notificação recebida | `webhook_receiver.py` | `webhook_receiver.mjs` | `webhook_receiver.php` | `WebhookReceiver.java` | | Fluxo completo das 5 etapas | `full_flow.py` | `full_flow.mjs` | `full_flow.php` | `FullFlow.java` | Cada linguagem tem seus testes ao lado do módulo, incluindo o vetor HMAC oficial, que roda offline. Rode tudo com `bash scripts/run_all_gates.sh`. O exemplo Java é autoral: a documentação oficial não publica sample nessa linguagem. ## Manutenção `python3 scripts/check_docs_drift.py` compara o `llms.txt` e o conteúdo das 31 páginas com `docs-inventory.json` e falha se a documentação oficial mudou — sinal de que este pacote precisa ser revisto antes de continuar a ser usado como referência.