(INPERA Dashboard) Integração Bradesco e geração de boleto de cobrança
Resumo da Nota Técnica
Nesta ordem de serviço foi implementada a integração com o banco Bradesco para emissão e registro de boletos de cobrança no sistema, incluindo o cadastro da integração, a validação das credenciais, a liberação do aviso de pagamento (webhook) e a geração do boleto na rotina operacional.
Com essa implementação, a empresa passa a emitir boletos Bradesco de forma integrada, desde a configuração inicial até a geração do documento, desde que os requisitos prévios junto ao banco estejam atendidos (Portal Developers, contrato de cobrança, códigos de registro e liberação do webhook).
Detalhes da Nota Técnica
1) Objetivo da funcionalidade
Permitir que o usuário configure a integração Bradesco no sistema e, a partir disso, gere boletos de cobrança registrados no banco, com linha digitável, código de barras e demais dados necessários para o recebimento.
2) Requisitos prévios junto ao Bradesco (obrigatórios antes de usar o sistema)
Antes de cadastrar a integração e emitir boletos, a empresa precisa concluir as liberações e contratações no Bradesco. Sem esses passos, o sistema pode autenticar as credenciais, mas o banco pode recusar o registro do boleto ou o recebimento dos avisos de pagamento.
2.1) Portal Developers Bradesco — criação e ativação da aplicação
É necessário criar e ativar a aplicação no Portal Developers do Bradesco, com a assinatura da aplicação e a geração das credenciais de acesso (Client ID e Client Secret). Essas credenciais serão informadas na tela de integração do sistema.
Também é necessário disponibilizar o certificado digital utilizado pela aplicação (conforme orientação do portal e do ambiente de produção ou testes), para que o sistema consiga se comunicar de forma segura com o Bradesco.
2.2) Contrato de cobrança com códigos 175 e 182 ativados
A empresa deve possuir contrato de cobrança Bradesco ativo e solicitar ao gerente ou à área de cobrança a ativação dos códigos:
- Código 175 — Registro via webservice (registro online de títulos);
- Código 182 — conforme contratação do banco para o fluxo de registro/cobrança utilizado na integração.
Sem esses códigos liberados no contrato/negociação, o Bradesco pode retornar mensagem de que o registro de títulos (e-commerce/API) não está contratado, mesmo com as credenciais da aplicação válidas.
2.3) Liberação do webhook (aviso de pagamento) por e-mail
Para que o sistema receba automaticamente a confirmação de pagamento dos boletos, é necessário solicitar a liberação do endpoint de webhook junto à governança de APIs do Bradesco, pelo e-mail:
governancaapis@bradesco.com.br
Nesse contato, a empresa deve informar os dados da aplicação, o endereço de recebimento do aviso de pagamento e seguir as orientações do banco sobre certificado e homologação do webhook. A liberação do webhook é independente da ativação da aplicação no portal: as credenciais podem estar ativas e o registro do boleto funcionar, enquanto o aviso automático de pagamento ainda depende dessa liberação.
2.4) Dados do contrato/negociação necessários para o cadastro
Para preencher a integração no sistema, a empresa precisa ter em mãos:
- Agência (sem dígito verificador);
- Conta (sem dígito verificador);
- Acessório Escritural Negociado;
- Identificador do produto de negociação (carteira).
Essas informações costumam constar no contrato/negociação de cobrança (Net Empresa / documentação bancária). Em caso de dúvida, devem ser confirmadas com o gerente Bradesco.
3) Cadastro da integração no sistema
Com os requisitos do banco atendidos, o usuário acessa a rotina de Integrações e cadastra a integração Bradesco.
3.1) Credenciais e certificados
Na tela de integração são informados:
- Client ID e Client Secret obtidos no Portal Developers;
- Certificados necessários para a comunicação segura com o banco (conforme o ambiente utilizado).
Em ambiente de produção, o sistema também pode auxiliar no uso do certificado A1 já configurado na empresa, quando disponível.
3.2) Dados do contrato de cobrança (formulário simplificado)
O formulário de contrato foi simplificado para quatro campos principais:
- Agência (sem dígito verificador);
- Conta (sem dígito verificador);
- Acessório Escritural Negociado;
- Identificador do produto de Negociação (Carteira).
A partir da agência e da conta, o sistema monta automaticamente o número de negociação no formato exigido pelo Bradesco. Os demais dados de acesso ao serviço de cobrança (como usuário de serviço e tipo de acesso) são preenchidos automaticamente pelo sistema, sem necessidade de digitação pelo usuário.
Quando existir exatamente uma conta bancária Bradesco cadastrada na empresa, o sistema tenta preencher automaticamente agência e conta. Se não houver conta Bradesco ou houver mais de uma, esses campos permanecem para preenchimento manual.
3.3) Validação ao salvar
Ao salvar a integração, o sistema realiza a checagem das credenciais junto ao Bradesco e tenta cadastrar o webhook de pagamento. A própria tela apresenta o status de cada etapa (integração salva, obtenção das credenciais de acesso e cadastro do webhook), com mensagens claras em caso de falha.
Importante: a integração pode ser salva com sucesso mesmo que o webhook ainda não esteja liberado pelo banco. Nesse caso, a emissão de boletos pode funcionar, mas a baixa automática por aviso de pagamento só ocorrerá após a liberação pela governança (e-mail indicado acima) e o cadastro bem-sucedido do webhook.
4) Geração do boleto Bradesco
Com a integração ativa, o usuário gera o boleto pela rotina de emissão/cobrança bancária já existente no sistema, selecionando a carteira/conta vinculada ao Bradesco.
Após o registro no banco, o sistema passa a guardar as informações do boleto, como:
- Nosso número;
- Linha digitável;
- Código de barras;
- Arquivo/PDF do boleto, quando gerado;
- Dados de Pix (quando a emissão for com cobrança mista/Pix liberada), como código copia e cola e identificadores retornados pelo banco.
O status do boleto é atualizado para registrado após o sucesso no Bradesco.
5) Situações tratadas e cuidados operacionais
- Credenciais incorretas ou aplicação inativa no Portal Developers: a etapa de autenticação falha e a tela informa o erro;
- Contrato sem código 175/182: o banco pode recusar o registro do título mesmo com a integração salva;
- Webhook não liberado: o boleto pode ser emitido, mas o aviso automático de pagamento pode não chegar até a liberação pela governança;
- Agência e conta informadas sem dígito verificador e no padrão esperado: o número de negociação é montado corretamente pelo sistema;
- Multa, juros e pagamento parcial: o sistema envia os dados de forma consistente com as regras do Bradesco (por exemplo, quando não há pagamento parcial, a quantidade correspondente é enviada zerada; multa incompleta não é enviada parcialmente).
6) Resultado para o usuário
Com a integração Bradesco disponível, a empresa centraliza no sistema o cadastro das credenciais, a configuração do contrato de cobrança e a emissão do boleto, reduzindo o trabalho manual e alinhando o processo às exigências do banco para registro online e acompanhamento de pagamento.
Observação:
As liberações no Portal Developers, a ativação dos códigos 175 e 182 no contrato e o e-mail à governança de APIs são responsabilidades da empresa junto ao Bradesco. O sistema utiliza essas liberações, mas não as substitui.
Parâmetros Envolvidos
- Client ID e Client Secret (Portal Developers Bradesco);
- Certificados da aplicação / certificado A1 da empresa (quando aplicável);
- Agência (sem dígito verificador);
- Conta (sem dígito verificador);
- Acessório Escritural Negociado;
- Identificador do produto de Negociação (Carteira);
- Ativação dos códigos 175 e 182 no contrato de cobrança Bradesco;
- Liberação do webhook junto à governança de APIs (governancaapis@bradesco.com.br).
