Averbação e Desaverbação
A constituição da garantia na Dataprev depois da formalização: os webhooks de sucesso e falha, a retentativa automática ("teimosinha"), a correção de dados e a desaverbação.
A garantia só está de fato constituída (collateral_constituted: true) depois da averbação aceita. Para os motivos de falha, veja Enumeradores.
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.
Para que o pedido de averbação seja criado com sucesso, é preciso que seja feita uma consulta de dados válida para o benefício previamente. Para isso basta seguir os passos do item 2 - Consulta de dados do benefício.
Falha na averbação por margem exedida
Se uma reserva com categoria de novo beneficiário ou de aumento salarial receber margem excedida na tentativa de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro", e será enviado um webhook no seguinte formato para informar o ocorrido:
Webhook Body
- Novo Beneficiario
- Aumento Salarial
{
"webhook": {
"key": "<DEBT-KEY>",
"data": {
"enumerator": "margin_exceeded_for_new_beneficiary",
"description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18",
},
"status": "pending_requester_action",
"webhook_type": "social_security_margin_exceeded_for_new_beneficiary",
"event_datetime": "2024-10-15T15:33:59"
}
}
{
"webhook": {
"key": "<DEBT-KEY>",
"data": {
"enumerator": "margin_exceeded_for_minimum_wage_increase",
"description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18",
},
"status": "pending_requester_action",
"webhook_type": "social_security_margin_exceeded_for_minimum_wage_increase",
"event_datetime": "2024-10-15T15:33:59"
}
}
Falha na averbação por falta de uma consulta de dados válida do benefício
Se uma consulta dos dados do benefício não for realizada com sucesso antes do pedido de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro" e será enviado um webhook no seguinte formato para informar o ocorrido:
Webhook Body
{
"webhook": {
"key": "<DEBT-KEY>",
"data": {
"enumerator": "success_balance_request_not_found",
"description": "Success balance request not found for the specified benefit number"
},
"status": "pending_requester_action",
"webhook_type": "social_security_success_balance_request_not_found",
"event_datetime": "2024-10-15T15:33:59"
}
}
Para prosseguir, as seguintes ações deverão ser tomadas:
- Realizar a consulta dos dados do benefício em questão seguindo os passos do item 2 - Consulta de dados do benefício;
- Enviar uma requisição no formato abaixo para informar que a consulta foi realizada.
Essa requisição não apenas confirma a existência de uma consulta válida dos dados do benefício, mas também verifica se as informações enviadas para a criação da averbação estão corretas, permitindo assim a continuidade do processo.
Sistema de priorização de requisições (Fura fila)
Devido à limitação da Dataprev, que permite no máximo 25 requisições por segundo, o sistema de requisições opera de maneira assíncrona, ou seja, as tentativas de averbação são organizadas em uma fila para processamento. Dessa forma, as requisições são priorizadas com base no tipo de operação e probabilidade de sucesso.
Nesse contexto, pensando em evitar a perda de margem em situações em que há alta probabilidade de sucesso na averbação, mas ainda vai demorar para ocorrer a próxima tentativa de averbação, foi desenvolvido esse sistema que permite realizar uma requisição de forma síncrona, ou seja, sem precisar esperar passar pela fila.
Todavia, para garantir o controle adequado e evitar o uso indevido desse sistema, foi implementado um mecanismo de balde de fichas, que funciona da seguinte forma:
- Cada requisição consome uma ficha para ser realizada;
- Se a requisição resultar em uma averbação bem-sucedida, a ficha é devolvida ao balde;
- Caso contrário, a ficha é perdida;
- Existe um limite máximo de fichas por balde;
- Uma rotina de reposição de fichas é ativada periodicamente, para reabastecer as fichas perdidas até atingir o limite máximo;
- Se as fichas se esgotarem, novas requisições não poderão ser feitas até que a rotina reponha uma nova ficha.
Exemplo Sistema de Balde
Nesse exemplo, a configuração do balde é:
- Número máximo de fichas: 10
- Tempo de reposição: 30min
HORA 0: O balde é criado com sua capacidade máxima;
9min: Uma requisição é feita, mas o contrato não é averbado (erro), ocasionando na perda de 1 ficha;
17min: Uma requisição é feita e o contrato é averbado (sucesso), mantendo inalterado o número de fichas;
30min: Ocorre a primeira reposição de fichas, levando o balde a sua capacidade máxima novamente;
47min: 10 requisições são realizadas com sucesso e nenhuma ficha é perdida;
1h: Ocorre a segunda reposição de fichas, mas como o balde já está cheio, o número de fichas permanece inalterado;
1:12h: 5 requisições são realizadas com erro, levando a perda de 5 fichas;
1:30h: Ocorre a terceira reposição de fichas, deixando o balde com 6 fichas;
1:38h: 6 requisições são realizadas com erro, esgotando todas as fichas;
1:51h: Uma tentativa de requisição é feita, mas como o balde não possui nenhuma ficha, a requisição é barrada;
2h: Ocorre a quarta reposição de fichas, levando a balde a 1 ficha e permitindo novas tentativas de requisições;
Para fazer a requisição prioritária, basta bater no seguinte endpoint utilizando a DEBT-KEY correspondente à operação que deseja averbar:
Request
Response
Response Body - Sucesso
{
"max_bucket_capacity": 10,
"bucket_fill_rate_minutes": 30,
"available_tokens": 7,
"status": "pending_document_submission",
"next_refill_at": "2025-02-04T20:28:35Z"
}
Response Body - Erros
Erro na averbação:
{
"title": "Reservation Failed",
"description": "Last Response: consignable_margin_excceded, Tokens Available: 9, Next Refill At: 2025-02-04T20:18:35Z",
"translation": "Ultima resposta: consignable_margin_excceded, Fichas disponiveis: 9, Proxima Recarga: 2025-02-04T20:18:35Z",
"extra_fields": {},
"code": "SSC000083"
}
Erro de nenhuma ficha disponível:
{
"title": "Rate limit exceeded",
"description": "Request limit exceeded. No tokens available, next refill in 8 minutes.",
"translation": "Limite de solicitacoes excedido. Nenhuma ficha disponivel, proxima recarga em 8 minutos.",
"extra_fields": {},
"code": "SSC000080"
}
Por fim, é possível consultar as configurações atuais do balde sem a necessidade de realizar uma requisição no endpoint de priorização. Para isso, disponibilizamos o seguinte endpoint para consulta:
Request
Response
Response Body
{
"max_bucket_capacity": 10,
"bucket_fill_rate_minutes": 30,
"available_tokens": 7,
"next_refill_at": "2025-02-04T20:08:35Z"
}
Sucesso na averbação
Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:
Webhook Body
{
"key": "<DEBT-KEY>",
"data": {
"collateral_type": "social_security",
"collateral_constituted": true
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
Correção de dados no caso de falha na averbação
É possível corrigir os dados bancários, número do benefício e o nome do contrato em tentativa de averbação. Para isso basta utilizar a seguinte chamada:
Request Body
- Dados Bancários
- Número do Benefício
- Nome
{
"disbursement_bank_account": {
"bank_code": "123",
"account_digit": "1",
"account_branch": "1234",
"account_number": "5678",
"document_number": "12345678901"
}
}
{
"benefit_number": 1234567890
}
{
"name": "Nome do Beneficiário"
}
Desaverbação
A desaverbação de um contrato é realizada através da rota de cancelamento permanente. Essa rota coloca um status final no contrato, o qual não é passível de retentativa e dispara a desaverbação da margem averbada.
Para realizar o cancelamento definitivo, deve ser utilizado o seguinte endpoint:
Webhooks
Webhook Body
{
"key": "<DEBT-KEY>",
"data": {},
"status": "canceled_permanently",
"webhook_type": "debt",
"event_datetime": "2022-11-01 03:46:31"
}