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.
Como o Inter reporta um pagamento#
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 dessa 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#
Inter publica os intervalos de IP de onde suas notificações se originam, e aceitamos apenas callbacks desses endereços. Nada é necessário 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 em produção#
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
ABERTO → ATRASADO → PAGO. 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.