Procedimento Técnico de Callback
Introdução
Um callback é enviado automaticamente sempre que eventos específicos ocorrem no sistema, permitindo uma comunicação eficiente entre diferentes partes de uma aplicação. Esse mecanismo é amplamente utilizado, por exemplo, para notificar atualizações de status de propostas, eliminando a necessidade de verificações constantes por parte do nosso parceiro . Assim, as informações são recebidas de maneira automatizada e em tempo real. Esse recurso é fundamental para a automatização de processos, garantindo respostas rápidas e mantendo a comunicação fluida entre sistemas. Nesta documentação, apresentaremos de forma clara e objetiva como esse procedimento funciona, sua importância nas integrações e como utilizá-lo no desenvolvimento de soluções mais dinâmicas e eficazes.Os nossos webhooks não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos nos payloads dos webhooks retornados. Verifique a página de Atualizações e Comunicados.
Configurações
1
Configuração do parceiro
Os parceiros podem configurar como desejam receber as notificações (callbacks), definindo as seguintes características:
1.1
URL
O parceiro deve especificar a URL do callback que será chamada para o envio das informações.
1.2
Ambientes
O callback para acompanhamento dos status das propostas deve ser enviado tanto para o ambiente de homologação quanto para o ambiente de produção. Recomenda-se que sejam utilizadas URLs diferentes para cada ambiente.
1.3
Métodos de chamada
O parceiro pode selecionar o método HTTP para o envio do callback.Opções disponíveis incluem:•
POST
• GET
• PUT2
Autenticação
Para garantir a segurança do callback enviado, recomendamos que o parceiro defina um método de autenticação.Seguem abaixo os métodos de autenticação disponíveis:Opções disponíveis incluem:
Métodos de autenticação aceitos
| Autenticação | Chave | Exemplo de Token |
|---|---|---|
| Bearer Token | Authorization | Bearer eyJhbGciOiJIUzI1CI6IkpXVCJ9 |
| API Key | API-Key | 1234567890abcdef1234567890abcdef |
| Basic Authentication | Authorization | Basic dXNlcm5hbWU6cGFzc3dvcmQ |
| X-API-Key | X-API-Key | 0987654321fedcba0987654321fedcba |
| JWT (JSON Web Token) | Authorization | Bearer eyJhbGciOiJIUzI1NiIs |
| HMAC (Hash-based Message Authentication Code) | Authorization | HMAC 5d41402abc4b19d911017c592 |
Em todos os métodos de autenticação aceitamos até 255 caracteres.
3
Exemplo de callback de proposta
Segue exemplo de URL e como parametrizamos para recebimento:
Observação: Caso o callback seja enviado com o método POST, além dos dados enviados na Query, o parceiro receberá no corpo da requisição:
Tabela dos parâmetros do callback da proposta
| Parâmetro | Descrição do parâmetro |
|---|---|
| Proposta | Guid único gerado no response durante a inclusão da proposta. |
| Situação | ID da situação da proposta em nosso sistema. |
| Identificador | Caso seja enviado, esse campo representa o código da operação enviado na inclusão da proposta. |
Tabela de identificação de status de proposta
| ID | Descrição | Objetivo |
|---|---|---|
| 2 | Aprovada | Proposta foi criada e está aguardando a assinatura. |
| 4 | Cancelada | Proposta foi cancelada automaticamente ou pelo integrador. |
| 5 | Pendente | Proposta foi marcada como pendente e necessita de intervenção do integrador para ser solicitada a averbação novamente. |
| 6 | Finalizada | Foi solicitada a averbação na CEF (Caixa Econômica Federal). |
| 8 | Liberada | Proposta averbada com sucesso e liberada para ser feito o desembolso. |
| 9 | Paga | Foi realizado o desembolso da proposta. |
| 10 | Cedida | Proposta foi adicionada em uma remessa de cessão e cedida ao fundo. |
| 11 | Pendente Pagamento | Proposta foi marcada como pendente de pagamento devido à inconsistência em dados bancários, necessitando de intervenção do integrador para informar os dados corretos de pagamento e retornar para a fila de pagamento. |
- Status 9: “00 - Crédito ou débito efetivado”
- Status 11: “AB - Descrição da ocorrência”
Caso ocorra algum problema durante o recebimento do callback de proposta, o sistema realizará até 3 tentativas de envio.
4
Callback do FGTS
O sistema de callback do FGTS é uma solução automatizada que permite o monitoramento em tempo real de cancelamentos de propostas e para retorno de simulações assíncronas de saldo.
4.1
Parametrização
Segue exemplo de URL e como parametrizamos para recebimento:
4.2
Eventos do FGTS
Os seguintes eventos podem acionar o envio de notificações ao callback configurado:
Boleto Registrado
Esse callback é enviado quando é solicitado o cancelamento de uma proposta e enviamos um boleto híbrido referente ao cancelamento.Cancelamento efetivado
Esse callback é enviado quando o parceiro gera um boleto de cancelamento e o cliente realiza o pagamento do boleto. Dessa forma, o cancelamento é executado com sucesso.Pagamento parcial
Esse callback é enviado quando o cliente realiza o pagamento parcial do valor do boleto.Pagamento não realizado
Esse callback é enviado quando o parceiro gera um boleto de cancelamento, mas o cliente não realiza o pagamento do boleto.Cancelamento não efetivado
Esse callback é enviado após o envio do call-back do “Pagamento não Realizado”. Informando que o cancelamento da operação não foi efetivado.Simulação batch concluída
Esse callback é enviado quando o parceiro solicita uma simulação assíncrona e o retorno da consulta já está pronto para ser consultado.Caso ocorra algum problema durante o recebimento do callback do FGTS, o sistema não realizará novas tentativas de envio