Cobertura

Cada instituição na API de Gerenciamento de Boleto fala a mesma API: uma solicitação para registrar uma cobrança, uma forma de resposta, um conjunto de status, um webhook boleto/updated. O que difere entre os bancos é como uma Conexão de Boleto é estabelecida — o que seu cliente precisa fornecer e se ele fornece isso a você ou ao banco.

Instituições#

IDs dos conectores, para GET /connectorsAPI: Inter Empresas 225, Bradesco 285, Sandbox 600.

Inter Empresas#

Inter é a implementação de referência: tudo abaixo acontece por trás dos mesmos endpoints descritos no guia da API de Gerenciamento de Boleto.

Credenciais. O Inter autentica com quatro artefatos — um Client ID, um Client Secret, uma chave privada e um certificado — criados dentro do próprio Internet Banking do Inter. Ao criar a integração no Inter, habilite os escopos Boleto e Extrato: uma credencial sem o escopo de Boleto conecta-se com sucesso e depois falha na primeira tentativa de emissão, que é um lugar confuso para descobrir o problema.

Duas maneiras de conectar. Passar por um Item é o melhor padrão quando você já coleta dados da conta para o mesmo cliente: uma conexão, um conjunto de credenciais, e o cliente autoriza uma vez. Enviar as credenciais diretamente é para quando não há um Item para reutilizar.

Como o Inter reporta um pagamento. O Inter nos notifica e traduzimos seu vocabulário nos status que a API expõe:

Quando um boleto se torna PAID, o Inter também reporta o que foi realmente pago e como, que vai para amountPaid e paymentOrigin (tipicamente PIX ou BOLETO).

Notificações. O Inter publica os intervalos de IP de onde suas notificações se originam, e só aceitamos callbacks desses endereços. Nada é exigido de você — o que você recebe é nosso próprio webhook boleto/updated, autenticado da mesma forma que todos os outros webhooks do Pluggy.

Vale a pena saber antes de você entrar ao vivo

• nossoNumero é do Inter, e seu formato é do Inter. Não o analise ou assuma uma largura; ele diferirá do que outra instituição retorna para a mesma cobrança.
• Um pagamento atrasado é normal. O Inter aceita pagamento após a data de vencimento, então um boleto pode passar de OPEN → OVERDUE → PAID. Manipuladores que param de ouvir uma vez que um boleto está atrasado perdem receita real.
• Reconcile com amountPaid, não amount. Descontos, multas e juros fazem com que eles diferem em ambas as direções.

Bradesco#

A emissão de boletos do Bradesco ainda não está disponível. O modelo que está sendo construído é descrito aqui para que você possa planejar; os endpoints e o fluxo de conexão não estão ativos, e os detalhes podem mudar à medida que a integração for finalizada.

Todas as outras instituições nesta API funcionam da mesma forma: seu cliente entrega credenciais, nós as mantemos e agimos com elas. O Bradesco separa identificar o chamador de autorizar a ação:

O certificado identifica o Pluggy como o parceiro. É nosso, não do seu cliente, e é o mesmo certificado para cada empresa para a qual atuamos — não há certificado por cliente a ser coletado, instalado ou renovado.

A autorização é concedida uma vez por empresa, por essa empresa, dentro do próprio ambiente do Bradesco. O Bradesco confirmou que isso não pode ser feito através de uma API: a pessoa que autoriza faz login no Bradesco, aceita os termos e confirma com uma chave de segurança gerada em seu próprio dispositivo. Nunca vemos a senha, a chave ou os termos que estão sendo assinados. Sem a autorização, o certificado sozinho não emite nada; sem o certificado, a autorização é inutilizável.

O que isso significa para sua integração. Conectar uma conta do Bradesco envolverá um redirecionamento: seu cliente sai da sua interface, autoriza no Bradesco e retorna. Essa é uma forma diferente do formulário de credenciais usado para o Inter, e introduz um estado que um fluxo apenas de credenciais nunca tem — uma conexão que existe, mas ainda não é utilizável. Vale a pena projetar isso agora se o Bradesco estiver no seu roadmap.

Ainda sendo resolvido com o Bradesco: o contrato exato do callback que confirma uma autorização; se uma autorização expira, e se revogá-la dentro do Bradesco produz alguma notificação; o caminho de integração para empresas que ainda não são titulares de conta no Bradesco; como uma empresa com vários CNPJs autoriza para todos eles.

Sandbox#

Testar uma integração de boleto contra um banco real é lento e parcialmente impossível: você precisa de uma conta empresarial, um pagador real disposto a pagar uma cobrança real, e para qualquer coisa envolvendo uma data de vencimento você teria que esperar a data chegar. O conector Sandbox é destinado a remover tudo isso — boletos que parecem reais, movidos para qualquer status sob demanda, disparando os mesmos webhooks que um banco real faria.

Ainda não está disponível: o conector Sandbox não aceita conexões de boleto hoje. Quando isso acontecer, seus boletos terão uma linha digitável corretamente formatada, código de barras e payload de PIX para que sua análise e renderização sejam testadas, mas eles não serão instrumentos de pagamento válidos — nada emitido lá pode ser pago em um banco real.