Como integrar a Atys ao Banco do Brasil para emitir e dar baixa em boletos?
O que você tem ao final do processo
É importante conhecer o resultado final para verificar se cada etapa foi concluída corretamente. Ao final do processo, quatro itens estarão prontos simultaneamente.
Resultado esperado: uma aplicação em produção no Portal Developers BB, vinculada ao CNPJ e ao convênio de cobrança corretos, com as credenciais técnicas disponíveis e o Webhook de baixa operacional apontando para a Atys.
Quem faz o quê
Uma dúvida frequente diz respeito à divisão de responsabilidades. A regra é clara: todas as atividades relacionadas ao banco são de responsabilidade do cliente, enquanto as tarefas técnicas e de código são de responsabilidade da Atys.
| Cliente | Equipe Atys |
|---|---|
| Fazer o login e as validações bancárias | Orientar o processo e conferir os dados técnicos |
| Escolher CNPJ, convênio e conta | Implementar e testar a integração |
| Autorizar a produção quando solicitado | Confirmar o recebimento do Webhook |
| Compartilhar somente credenciais técnicas | Armazenar as credenciais com segurança |
Antes de começar: o que precisa estar pronto
A maioria dos problemas nesse cadastro é de natureza cadastral, não técnica. Um convênio não contratado ou um usuário sem permissão para representar a empresa pode interromper o processo. Verifique os itens a seguir antes de acessar o portal.
- CPF com acesso ao Portal Developers do BB
- CNPJ da empresa que vai usar a integração
- Conta corrente de pessoa jurídica ativa no Banco do Brasil
- Convênio de cobrança contratado e ativo
- Permissão para representar ou administrar a empresa
- Acesso aos canais de autenticação exigidos pelo BB (aplicativo, token, SMS)
Requisito da API: a API Cobranças é exclusiva para pessoas jurídicas e depende de um convênio de cobrança. Se o convênio não aparecer em momento algum do processo, provavelmente não está habilitado. Confirme com o gerente da sua conta no Banco do Brasil antes de prosseguir.
Dados que você vai precisar ter em mãos
Registre esses números com antecedência, preferencialmente consultando o contrato do convênio. Eles serão solicitados em diferentes etapas e é comum que ocorram erros ao informar a carteira e a variação.
- CNPJ da empresa titular da conta
- Número do convênio de cobrança contratado com o BB
- Agência e conta corrente onde os boletos serão liquidados
- Carteira e variação definidas no contrato do convênio
A integração em dez passos
Antes de acessar o portal, revise todo o processo. Nenhum passo pode ser ignorado e a ordem é fundamental: as credenciais de teste só ficam disponíveis após a criação da aplicação, e o pedido de produção só deve ser feito após a aprovação dos testes.
Passo a passo detalhado
Entrar no Portal Developers BB
O acesso é feito pelo próprio cliente em acesso.bb.com.br, utilizando o CPF do responsável pela aplicação. O portal realiza uma verificação de segurança e, em seguida, solicita a autenticação bancária habitual.
- Acesse o Portal Developers BB no navegador.
- Informe o CPF do responsável pela aplicação.
- Conclua a verificação de segurança exibida na tela.
- Clique em AVANÇAR e finalize a autenticação solicitada pelo Banco do Brasil.
Atenção à segurança: a Atys nunca solicitará sua senha bancária, senha do portal, códigos por SMS, token, QR Code ou qualquer outro código de autenticação. Caso alguém solicite essas informações em nome da Atys, não as forneça e comunique imediatamente à nossa equipe.
Abrir a área de aplicações
Após o login, o portal exibe a lista de aplicações existentes. A partir dessa tela, é possível criar uma nova aplicação. Caso sua empresa possua mais de um perfil ou CNPJ, confirme que está selecionando o correto antes de prosseguir.
- No menu superior, abra Central de Gestão.
- Entre na seção Aplicações.
- Confirme que está no CNPJ ou perfil correto, quando o portal pedir essa escolha.
- Clique em CRIAR NOVA APLICAÇÃO.
Organização: o portal permite criar várias aplicações, como uma para testes, outra para produção e outras para diferentes integrações. Para facilitar a manutenção posterior, mantenha uma aplicação exclusiva para a integração com a Atys Cobranças V2, sem misturá-la a outros sistemas.
Nomear e descrever a aplicação
Neste momento, o portal solicita um nome e uma descrição para a aplicação. Esses dados facilitam a identificação futura da aplicação. Utilize nomes que indiquem claramente a finalidade da aplicação.
| Campo | Conteúdo sugerido |
|---|---|
| Nome da aplicação | ATYS Cobrancas |
| Descrição | Integração do sistema ATYS com a API Cobranças V2 do Banco do Brasil para emissão, consulta, alteração, baixa e acompanhamento de boletos. |
Atenção ao limite de caracteres: o portal exibe o limite de cada campo, como 20 para o nome e 200 para a descrição. Caso o texto não seja aceito, reduza a descrição sem alterar a finalidade da aplicação.
Selecionar a API Cobranças (V2)
Este é um dos passos mais suscetíveis a erros, pois a tela apresenta várias APIs semelhantes, como Pix, Extratos, BB Pay e Pagamentos em Lote. Para integrar boletos à Atys, selecione Cobranças (V2). As demais opções exigem contratações distintas e não atendem a esse objetivo.
- Role a página até encontrar o cartão COBRANÇAS (V2).
- Leia os requisitos listados no cartão: convênio de cobrança, cadastro no portal e CNPJ.
- Marque a caixa SELECIONAR desse cartão.
- Não marque Extratos, BB Pay ou qualquer outra API, a não ser que a Atys peça expressamente.
- Siga até concluir a criação da aplicação.
Confira antes de concluir: a aplicação precisa mostrar a API Cobranças (V2) como vinculada. Se aparecer outra API na lista, volte e corrija, pois trocar isso depois costuma dar mais trabalho do que refazer agora.
Conferir a aplicação e o ambiente de teste
Após a criação, a aplicação inicia normalmente no ambiente de testes. Essa etapa é padrão e não indica erro. O ambiente de produção só é liberado mediante solicitação específica, realizada em etapas posteriores.
- Volte para a lista de Aplicações.
- Abra o cartão da aplicação recém-criada.
- Confirme o nome, o CNPJ e a API Cobranças (V2).
- Acesse a seção Credenciais.
- Identifique com clareza se as credenciais são de teste ou de produção.
Não misture ambientes: credenciais, URLs e tokens de teste não funcionam em produção, e vice-versa. Sempre identifique o ambiente das credenciais em suas anotações e nas comunicações com a Atys. Muitos erros de integração ocorrem nesta etapa.
Os status que podem aparecer
A aplicação está disponível para validações no ambiente de testes. É o estado inicial normal.
A solicitação está sendo avaliada pelo Banco do Brasil. Só resta aguardar o retorno.
Existe uma pendência comercial ou bancária. Fale com o gerente da conta.
A aplicação está liberada para uso real, com boletos válidos.
Localizar as credenciais técnicas
Na área Credenciais, o portal exibe as chaves que a Atys usará para autenticar-se no banco. Os nomes variam um pouco conforme a tela, mas são sempre estes três.
- App Key — também chamada de Developer Application Key. Identifica a aplicação no portal.
- Client ID — identifica quem está pedindo o acesso.
- Client Secret — a senha dessa credencial. É o dado mais sensível dos três.
O que enviar para a Atys: apenas as credenciais técnicas da aplicação e os dados do convênio. Não envie senhas pessoais, códigos de autenticação ou acesso ao Internet Banking, pois a integração não precisa disso em momento algum.
Modelo para envio seguro
Ambiente: TESTE ou PRODUÇÃO
Nome da aplicação: ____________________
CNPJ: ____________________
Client ID: ____________________
Client Secret: ____________________
App Key: ____________________
Convênio: ____________________
Agência/Conta: ____________________
Carteira/Variação: ____________________Proteja o Client Secret: trate-a como uma senha. Não a publique em tickets abertos, repositórios Git, capturas de tela ou grupos de mensagens com participantes não autorizados. Em caso de vazamento, gere uma nova chave no portal e informe a Atys.
Validar no ambiente de teste
Com as credenciais de teste em mãos, a Atys executa a jornada completa de cobrança em um ambiente em que nada é cobrado de fato. É aqui que aparecem divergências de convênio, de carteira ou de variação, o que é muito melhor descobrir agora do que com um boleto real em circulação.
- Autenticação e geração do access token
- Registro ou emissão de cobrança conforme a jornada contratada
- Consulta de uma cobrança
- Alteração dos dados permitidos, quando aplicável
- Baixa ou cancelamento, quando aplicável
- Tratamento das respostas de erro
- Validação dos dados de convênio, carteira e variação
- Registro de logs sem expor credenciais
Critério para avançar: solicite a produção apenas após a confirmação da Atys de que as credenciais de teste e os dados do convênio permitem executar a jornada esperada. Guarde o identificador da aplicação, a data dos testes e exemplos de respostas sem dados sensíveis, pois esse registro é útil em eventuais questionamentos.
Enviar a aplicação para produção
Após a aprovação dos testes, solicite o uso em produção diretamente na aplicação, pelo portal. O pedido será analisado pelo banco, e o prazo de liberação depende do Banco do Brasil e pode variar conforme a contratação.
- Abra a aplicação no Portal Developers BB.
- Procure a ação ENVIAR PARA PRODUÇÃO ou opção equivalente.
- Selecione o CNPJ e o convênio corretos, caso sejam solicitados.
- Preencha as informações complementares e aceite os termos apresentados.
- Conclua as autenticações bancárias solicitadas.
- Acompanhe o status até a liberação.
Sobre as credenciais de produção: segundo o Portal de Apoio do BB, elas seguem um fluxo próprio, separado do de teste. Confira a área da aplicação após a liberação e siga exatamente as instruções que o portal exibir para liberá-la.
Quando falar com o gerente do Banco do Brasil
- O convênio não aparece em nenhuma tela
- O convênio aparece como inativo ou incompatível
- A opção de envio para produção não está disponível
- A empresa não consegue concluir a contratação
- Os dados da conta ou do CNPJ estão divergentes
Entender o Webhook de baixa operacional
O webhook é o elemento que finaliza o ciclo de integração. Trata-se de um aviso automático: em vez de a Atys consultar periodicamente o banco sobre o pagamento do boleto, o próprio banco envia uma notificação imediata para o endereço cadastrado.
Na API Cobrança, o evento previsto na documentação oficial do BB é o recebimento de uma baixa operacional de boleto. Na prática: o cliente paga, o banco dispara o aviso e a cobrança é baixada na Atys, sem que ninguém precise conferir o extrato. É o mesmo princípio que usamos nas integrações de cobrança via Pix, boleto e cartão do módulo Financeiro.
URL oficial da integração Atys:
https://webhook-bb.atys.pro/api/banco-do-brasil-baixa-operacionalPré-requisitos para o Webhook
- Aplicação liberada no ambiente em que o webhook será usado
- Convênio correto selecionado
- Endpoint HTTPS informado exatamente como a Atys forneceu
- URL acessível publicamente, sem redirecionamento manual
- Confirmação da Atys de que o endpoint está pronto para receber eventos
A URL precisa ser idêntica: não acrescente barra no final, parâmetros, espaços ou qualquer caractere extra, a menos que a Atys peça expressamente. Um caractere a mais e o banco entrega o aviso em um endereço que não existe.
Cadastrar o Webhook no portal
Com a aplicação liberada e a URL em mãos, o cadastro em si é rápido. Ele é feito na aplicação Cobranças (V2), na área de webhooks ou de gerenciamento de eventos.
- Abra a aplicação Cobranças (V2).
- Acesse a área Webhook ou a opção de gerenciamento de eventos do portal.
- Clique para cadastrar um novo evento.
- Selecione a API Cobranças e o convênio correspondente.
- Escolha o evento relacionado à baixa operacional.
- No campo da URL, cole exatamente o endereço abaixo.
- Ative o evento e salve a configuração.
https://webhook-bb.atys.pro/api/banco-do-brasil-baixa-operacionalConfira cada caractere antes de salvar: o domínio deve ser webhook-bb.atys.pro e o caminho deve terminar em /api/banco-do-brasil-baixa-operacional. Anote também a data do cadastro, o responsável, o convênio e o status exibido, pois esse registro facilita eventuais verificações futuras.
Testar e resolver os problemas mais comuns
Salvar a configuração não garante seu funcionamento. Realize uma verificação final em conjunto com nossa equipe antes de considerar a integração concluída.
- Confirme que o evento está ativo no portal.
- Envie à Atys uma captura da configuração, sem expor credenciais.
- Peça à Atys a confirmação de que o endpoint está acessível.
- Quando disponíveis, use os recursos de teste via Sandbox descritos pelo BB.
- Após um evento real ou simulado, confirme o processamento na Atys.
| Situação | O que fazer |
|---|---|
| URL recusada pelo portal | Verifique o HTTPS, a digitação e se o endereço está publicamente acessível. |
| O evento de baixa não aparece | Confirme a API, o ambiente, o convênio e se o recurso está liberado. |
| A notificação não chega | Confirme se o evento está ativo e peça verificação técnica à Atys. |
| O convênio não está disponível | Valide a contratação com o gerente do Banco do Brasil. |
| Erro de autorização | Revise o perfil do usuário e o vínculo dele com o CNPJ. |
Depois que estiver funcionando, avise antes de mexer: não troque a URL, não desative o evento nem exclua a aplicação sem alinhar com a Atys. Qualquer uma dessas ações interrompe a baixa automática das cobranças, e o efeito só costuma ser percebido dias depois, na conciliação.
Checklist final
- Aplicação criada com um nome identificável
- API Cobranças (V2) vinculada à aplicação
- CNPJ e convênio conferidos
- Credenciais de teste validadas
- Solicitação de produção concluída
- Credenciais de produção enviadas com segurança
- Webhook cadastrado com a URL correta
- Evento de baixa operacional ativo
- Atys confirmou o recebimento ou a disponibilidade do endpoint
- Equipe orientada a nunca compartilhar senhas bancárias
Fontes oficiais do Banco do Brasil
Todo o roteiro acima segue a documentação pública do Portal de Apoio aos Desenvolvedores do BB. Consulte sempre a fonte oficial em caso de dúvida ou de mudança de tela.