Inter Empresas é a primeira instituição disponível na Referência da API de Gestão de Boletos, e a implementação de referência: tudo nesta página acontece por trás dos mesmos endpoints descritos no guia da Referência da API de Gestão de Boletos.
Estabelecendo uma conexã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. O tutorial do Banco Inter Empresas orienta sobre como produzi-los.
Ative as permissões corretas
Ao criar a integração no Inter, ative os escopos Boleto e Extrato. Uma credencial que não possui o escopo Boleto conecta-se com sucesso e depois falha na primeira tentativa de emissão, o que é um lugar confuso para descobrir o problema.
Existem duas maneiras de transformar essas credenciais em uma conexão:
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 credenciais diretamente é para quando não há um Item para reutilizar.
Várias Conexões de Boleto em uma integração do Inter#
O Inter aceita um único webhook de cobrança por integração. Registramos um webhook que atende a cada Conexão de Boleto nessa integração e roteamos cada notificação para o boleto certo pelo próprio identificador do Inter para a cobrança. Portanto, um par de Client ID + Client Secret pode suportar quantas Conexões de Boleto você precisar: outro aplicativo Pluggy, outra equipe, ou uma conexão recriada após uma exclusão, seja você a crie diretamente ou a partir de um Item.
Criar uma conexão em uma integração que já possui nosso webhook simplesmente mantém-no no lugar. Boletos emitidos em conexões anteriores da mesma integração, incluindo conexões que você excluiu desde então, continuam recebendo suas atualizações de status.
O único caso que não tocamos é um webhook de cobrança que outro sistema configurou na integração (seu próprio backend, um ERP, outro provedor). Substituí-lo cortaria silenciosamente aquele sistema, então criar a conexão falha com:
Não foi possível criar a boleto connection: A integração já tem um webhook de cobrança configurado por outro sistema. Por favor, exclua esse webhook para criar uma Boleto Connection ou crie uma integração nova sem webhook.
Para prosseguir, remova esse webhook (Inter's DELETE /cobranca/v3/cobrancas/webhook, com as credenciais daquela integração) assim que nada depender dele, ou crie outra integração no Inter para o Pluggy, com seu próprio Client ID, Client Secret e certificado, seguindo o tutorial do Banco Inter Empresas. Baixar um novo certificado para a mesma integração não ajuda: o webhook pertence à integração, não ao certificado.
Como o Inter reporta um pagamento#
O Inter nos notifica, e traduzimos seu vocabulário nos status que a API expõe:
Inter situacao | Torna-se |
|---|---|
RECEBIDO | PAID |
MARCADO_RECEBIDO | PAID |
ATRASADO | OVERDUE |
PROTESTO | PROTESTED |
A_RECEBER | ignorado — o boleto simplesmente ainda está aberto |
Quando um boleto se torna PAID, o Inter também reporta o que foi realmente pago e como, que vai para amountPaid e paymentOrigin. paymentOrigin é tipicamente PIX ou BOLETO, refletindo como o pagador escolheu liquidar.
Cancelamentos não chegam por webhook
Um boleto que você cancela através do POST /boletos//cancelAPI é marcado como CANCELLED imediatamente, como parte daquela chamada. Mas um boleto cancelado diretamente dentro do próprio portal do Inter não será atualizado do nosso lado — esse caminho não produz nenhuma mudança de status que você possa observar. Se sua equipe de operações cancela boletos no Inter em vez de através da API, trate nosso status como autoritativo apenas para boletos cancelados através da API.
Autenticando as notificações#
O Inter publica os intervalos de IP de onde suas notificações se originam, e nós aceitamos apenas callbacks desses endereços. Nada é exigido de você — a notificaçã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 difere do que outra instituição retornará 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. - Teste o caminho de pagamento parcial.
amountPaidpode ser menor ou maior queamountuma vez que descontos, multas ou juros se aplicam. O Sandbox o produz sob demanda: emita um boleto com um valor terminando em,01e ele será pago pela metade.