Como integrar a Atys ao Banco do Brasil para emitir e dar baixa em boletos?
Antes de começar
A maioria dos bloqueios nesse processo é cadastral, não técnica. Confira estes itens antes de abrir o portal:
- CPF do responsável, com e-mail e celular que ele acesse na hora
- CNPJ da empresa, com conta corrente PJ ativa no Banco do Brasil
- Convênio de cobrança contratado e ativo, com número, carteira, variação, agência e conta à mão (estão no contrato do convênio, no site bb.com.br em Cobrança > Configurações ou com o gerente)
- Representante legal da empresa disponível para assinar o termo de adesão
- Acesso à Atys com permissão para mexer em Configurações
Sem convênio de cobrança não há integração. A API Cobranças é exclusiva para CNPJ e depende dele. Se o convênio não estiver ativo, resolva com o gerente da sua conta antes de começar.
O processo em quatro fases
Siga na ordem: as credenciais que vão para a Atys só existem depois que o aplicativo é liberado para produção.
Fase A · Criar o aplicativo no Portal Developers BB
Entrar no Portal Developers BB
Acesse o Portal Developers BB (app.developers.bb.com.br) com o CPF do responsável.
- Informe o CPF e conclua a verificação de segurança.
- Clique em AVANÇAR, informe a senha e finalize a autenticação.
Primeiro acesso? Veja como criar a conta
Se o CPF ainda não tem conta, o portal abre o cadastro em quatro telas, sempre com o botão AVANÇAR no fim.
- Dados pessoais: nome completo e data de nascimento (o CPF já vem preenchido).
- E-mail: um endereço que você acessa na hora.
- Celular: com DDD.
- Senha: de 8 a 16 caracteres, com letra minúscula, letra maiúscula, número e caractere especial (@, !, #).
Se chegar uma confirmação no e-mail, conclua-a e volte ao portal para entrar.
Criar o aplicativo com a API Cobranças (V2)
Tudo acontece em uma única tela do portal, que o BB chama de "Nova aplicação". Neste guia, aplicativo e aplicação são a mesma coisa.
- Na tela Aplicações, clique em CRIAR NOVA APLICAÇÃO. Se não estiver nela, use o menu Central de Gestão > Aplicações.
- Preencha o nome (até 20 caracteres) e a descrição (até 200). Sugestão: ATYS Cobrancas e "Integração da ATYS com a API Cobranças V2 para emissão e baixa de boletos."
- Role até o cartão COBRANÇAS (v2) e marque SELECIONAR. Não marque nenhuma outra API: Pix, Extratos e BB Pay são contratações diferentes.
- No fim da página, clique em CRIAR.
O portal abre a tela de credenciais do ambiente de teste. A Atys não usa essas credenciais: clique em AVANÇAR. Na lista de aplicativos, confira o cartão novo e anote o número do ID.
CNPJ "-" e empresa "Não vinculada" são normais aqui. O vínculo com a empresa acontece no próximo passo.
Fase B · Liberar a produção
Enviar o aplicativo para produção
Abra o aplicativo no portal e escolha Enviar para produção. O formulário tem quatro etapas, numeradas no topo.
1. Identificação da empresa
- Digite o CNPJ da empresa titular do convênio e clique em PESQUISAR.
- Confira a razão social e clique em CONFIRMAR.
O CNPJ não pode ser trocado depois. Se ele estiver errado, só criando outro aplicativo.
2. Contato da aplicação
- Informe o e-mail (obrigatório) e, se quiser, o telefone. Prefira um e-mail da empresa lido por mais de uma pessoa, como financeiro@.
- Clique em CONFIRMAR.
3. Revisão da aplicação
- Confira CNPJ, razão social, a API Cobranças e o contato.
- Clique em CONFIRMAR.
4. Contratação
- Clique em CONCLUIR.
Assinar o termo de adesão
O aplicativo fica em Aguardando aprovação até o representante legal da empresa assinar o termo de adesão. Depois da assinatura, o banco libera a produção.
- Avise o representante legal de que há um termo de adesão para assinar.
- Ele assina no Portal Developers ou no BB Digital PJ.
- Acompanhe o selo do aplicativo na lista de Aplicações.
O termo não aparece para o representante? Fale com o gerente da sua conta no Banco do Brasil.
Fase C · Conectar na Atys
Copiar as credenciais de produção
Abra o aplicativo, entre em Credenciais e clique na aba Ambiente de produção. A tela é igual à do ambiente de teste mostrada abaixo.
O Client Secret aparece uma única vez. Antes de sair da tela, copie as três credenciais ou clique em BAIXAR TODAS AS CREDENCIAIS (TXT). Se perder, será preciso regerar.
- Copie a App Key, o Client ID e o Client Secret, ou baixe o arquivo TXT.
- Guarde em local seguro, como o gerenciador de senhas da empresa. Não mande por chat nem e-mail.
Os blocos Basic e Registration Access Token não são usados.
Conectar as credenciais na Atys
Você mesmo cola as credenciais na Atys, onde elas ficam cifradas. Ninguém da equipe precisa recebê-las.
- Na Atys, abra Configurações > Adquirentes e Sub-adquirentes.
- No cartão Banco do Brasil, clique em Configurar. Abre a janela "Configurar sua conta Banco do Brasil na ATYS".
- Cole o Client ID, o Client Secret e a App Key (no campo Developer App Key).
- Preencha os dados do convênio: convênio (4 a 7 dígitos), carteira, variação, agência e conta.
- Clique em Salvar. A Atys testa a conexão com o banco antes de gravar.
- Com a conexão OK, ative o gateway no cartão do Banco do Brasil, se ele ainda estiver desativado.
| Resultado ao salvar | O que fazer |
|---|---|
| Conexão OK | Pronto. Siga para o passo 7. |
| Falha na conexão, erro 401 | Revise as três credenciais: precisam ser da aba Ambiente de produção e sem espaços sobrando. |
| Falha na conexão, erro 403 | Confira no portal se o aplicativo está em Produção, com a API Cobranças e o convênio do mesmo CNPJ. |
| Não foi possível validar a outorga | A conexão funcionou, mas o banco não confirmou a permissão de cobrança. Fale com a equipe Atys antes de usar "Salvar mesmo assim". |
Fase D · Ligar a baixa automática
Cadastrar o webhook de baixa
O webhook é o aviso que o banco manda para a Atys quando um boleto é pago (o BB chama isso de baixa operacional). Com ele, a cobrança é baixada na Atys sem ninguém conferir extrato.
- No portal, abra o aplicativo da integração com a Atys e entre em Webhook.
- Na aba Eventos, clique em + Cadastrar novo evento.
- Em API selecionada, deixe Cobranças (v2).
- Em Tipo de evento, marque BAIXA OPERACIONAL.
- Em Convênio de cobrança, marque a linha do seu convênio. Confira número, carteira, variação, agência e conta.
- Em URL, cole exatamente o endereço abaixo.
- Clique em SALVAR.
https://webhook-bb.atys.pro/api/banco-do-brasil-baixa-operacional
A URL precisa ser idêntica: sem barra no final, sem espaços, sem parâmetros. Um caractere a mais e o banco entrega o aviso num endereço que não existe.
Na lista, a coluna Identificador mostra o número do convênio. Se algum aviso não chegar à Atys, o link Consultar erros do evento mostra o que o banco tentou enviar.
Conferir com a equipe Atys
Peça à equipe Atys a confirmação final e passe pela lista abaixo.
- Aplicativo em Produção, só com a API Cobranças (V2)
- CNPJ e convênio corretos no aplicativo
- Gateway Banco do Brasil salvo na Atys com Conexão OK
- Evento BAIXA OPERACIONAL cadastrado no Webhook, com a URL da Atys
- Equipe Atys confirmou que o endpoint está recebendo eventos
Depois que estiver funcionando, avise antes de mexer. Trocar a URL, desativar o evento, regerar credenciais ou excluir o aplicativo interrompe a baixa automática, e o efeito só costuma aparecer dias depois, na conciliação.
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.