Efí Bank
Esta página descreve como funciona a integração do nosso sistema com a API do Efí Bank. Atualmente utilizamos duas funcionalidades principais:
- Split de Pagamentos via Boletos
- Pagamento de Contas
Nosso objetivo com essa integração é automatizar processos financeiros, garantindo agilidade, segurança e rastreabilidade nas transações.
Visão Geral
A integração com o Efí Bank permite:
- Emissão e gerenciamento de boletos bancários com registro
- Acompanhamento de status e baixa automática
- Realização de pagamentos automatizados (fornecedores, contas, etc.)
- Controle de conciliação financeira integrada ao ERP
Autenticação
Toda comunicação com a API da Efí é feita de forma segura, utilizando OAuth2 para autenticação. Antes de realizar qualquer operação, o sistema obtém um access_token utilizando as credenciais fornecidas pela Efí (Client ID e Client Secret).
Esse token é incluído no header das requisições e tem validade temporária.
Obter Autorização
Endpoint:
POST /v1/authorize
Descrição:
O endpoint POST /v1/authorize é usado para autorizar as credenciais de uma aplicação e obter os acessos necessários para utilizar os outros recursos da API.
Split de Pagamentos (Boletos)
Essa funcionalidade permite que, ao emitir um boleto, o valor seja automaticamente dividido entre múltiplas contas Efí. É especialmente útil quando precisamos repassar comissões, taxas ou qualquer outra divisão automática de receita.
1. Criar Cobrança com Split
Endpoint:
POST /v1/charge/one-step
Descrição:
Esta é a rota que utilizamos no sistema para emissão de boletos com split. Ela realiza a criação da cobrança e a emissão do boleto em uma única chamada. Além disso, já permite configurar os dados do split (divisão de valores entre contas) diretamente no corpo da requisição.
2. Consultar Cobrança
Endpoint:
GET /v1/charge/:id
Descrição:
Utilizamos este endpoint para consultar os dados de uma cobrança criada anteriormente, incluindo status e informações do split.
3. Cancelar uma transação
Endpoint:
PUT /v1/charge/:id/cancel
Descrição:
Permite cancelar uma cobrança ainda não paga.
4. Notificações (Webhooks)
Nosso sistema é totalmente integrado ao serviço de notificações (webhooks) da Efí Bank. Essa funcionalidade permite que sejamos informados automaticamente sempre que uma cobrança muda de status – por exemplo, quando um boleto é pago, cancelado ou expira.
Como funciona
Sempre que ocorre uma alteração no status de uma cobrança (ex: pagamento confirmado), a Efí envia uma requisição HTTP POST para a URL que definimos no momento da criação da cobrança. Essa URL é o nosso endpoint de notificação, que está preparado para receber, validar e processar esses eventos.
URL de Notificação
Durante a criação de uma cobrança (especialmente na rota POST /v1/one-step que usamos), informamos o campo notification_url, que aponta para o endpoint do nosso sistema que irá receber os eventos.
Exemplo de campo:
"notification_url": "https://seudominio.com.br/api/efi/notification"
Fluxo da Notificação
- O cliente realiza o pagamento de um boleto.
- A Efí identifica a mudança de status da cobrança.
- É disparada uma requisição POST para a notification_url que informamos informando um token.
- Nosso sistema processa a notificação e atualiza o status da cobrança internamente.
O que fazemos ao receber a notificação
Assim que recebemos a notificação, nosso sistema:
- Consulta os dados da cobrança diretamente na Efí via
GET /v1/notification/:token. - Atualiza o status da cobrança em nosso banco de dados.
- Executa ações vinculadas, como baixa na mensalidade do cliente.
Pagamento de Contas
Também integramos com a funcionalidade de pagamento de boletos de terceiros. Isso nos permite, por exemplo, pagar contas de consumo, tributos, ou boletos de fornecedores diretamente pela API.
1. Detalhar Código de Barras
Endpoint:
GET /v1/codBarras/:codBarras
Descrição:
Antes de pagar qualquer boleto, precisamos detalhá-lo para obter informações como valor, vencimento e quem é o beneficiário. Esse passo é obrigatório para validação.
2. Solicitar Pagamento
Endpoint:
POST /v1/codBarras/:codBarras
Descrição: Aqui é onde efetivamente solicitamos o pagamento do boleto. Podemos definir se o pagamento será feito no mesmo dia ou agendado para uma data futura.
3. Consultar Pagamento Solicitado
Endpoint:
GET /v1/:idPagamento
Descrição:
Após solicitar o pagamento, utilizamos esse endpoint para verificar o status da transação: se foi paga, se houve falha ou se ainda está em processamento.
4. Webhooks
Endpoint:
PUT /v1/webhook
Descrição:
Endpoint para criação do webhook de pagamento.
Recebendo Callbacks
Esse serviço está protegido por uma camada de autenticação mTLS. Os callbacks são enviados pela Efí via POST url-webhook-cadastrada quando há uma alteração no status do Pagamento.
Requisição
Quando ocorre uma alteração no status de um pagamento associado a aplicação utilizada,
a Efí envia uma requisição POST para a URL de webhook que foi definida.
Cada requisição de callback possui um timeout de 60 segundos, ou seja,
é interrompida se não houver resposta em 60 segundos.