Consulta de Dados do Benefício
Consulta saldo, margem e situação de um benefício (POST /social_security/balance_request). Uma consulta de dados válida é pré-requisito da averbação: sem ela, o pedido de averbação fica pendente de ação do parceiro.
A consulta pode ser feita com o Termo de Autorização já enviado na consulta da lista de benefícios, ou enviando o termo na própria requisição.
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.
Caso 1 — Termo de Autorização previamente enviado
Consulta de dados do benefício com o Termo de Autorização previamente enviado.
Request
Request Body
{
"document_number": "14950479032",
"benefit_number": "22255220"
}
Response
Response Body
{
"balance_request_key": "<GUID DA CONSULTA DE DADOS DO BENEFÍCIO>",
"status": "pending_search"
}
Caso 2 — Termo de Autorização enviado na própria consulta
Consulta de dados do benefício com envio do Termo de Autorização.
Request
Request Body
{
"document_number": "14950479032",
"benefit_number": "22255220",
"authorization_term": {
"document_number": "14950479032",
"legal_representative_document_number": "87237271016",
"signature": {
"signer": {
"name": "Maria da Silva",
"email": "maria.silva@email.com",
"phone": {
"number": "999538380",
"area_code": "11",
"country_code": "55"
},
"document_number": "87237271016"
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "2024-11-07T14:28:23.382748Z",
"ip_address": "179.145.48.219",
"fingerprint": {},
"third_party_additional_data": {},
"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
},
"signed_object": {
"document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383"
}
}
}
}
O termo de autorização tem validade de 30 dias após a assinatura. Durante o periodo hábil, é possível consultar os dados do benefício sem reenviar autorização do cliente. Caso não tenha sido enviada a autorização, é necessário enviar o termo durante esta requisição.
Nos casos em que houver representante legal, é necessário preencher o campo "legal_representative_document_number" com o CPF do representante legal, e os dados do objeto "signer" devem ser preenchidos com os dados do mesmo.
Response
Response Body
{
"balance_request_key": "<GUID DA CONSULTA DE DADOS DO BENEFÍCIO>",
"status": "pending_authorization"
}
Webhook de sucesso
Em caso de sucesso na consulta de dados do benefício
Webhook Body
{
"webhook_type": "social_security_balance_request",
"key": "<GUID balance_request_key>",
"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
"status": "success",
"data": {
"name": "IVOLANDO MIRANDA",
"state": "SP",
"alimony": "not_payer",
"birth_date": "07021961",
"grant_date": "2022-09-02",
"credit_type": "checking_account",
"block_type": "not_blocked",
"benefit_card": {
"limit": 2083.2,
"balance": 0
},
"benefit_number": "22255220",
"benefit_status": "elegible",
"payroll_card": {
"limit": 2083.2,
"balance": 0
},
"assistance_type": "retirement_by_age",
"document_number": "14950479032",
"benefit_end_date": "2020-12-01",
"consigned_credit": {
"balance": 1000
},
"benefit_situation": "active",
"max_total_balance": 2000,
"used_total_balance": 1000,
"politically_exposed": {
"type": "politically_exposed_level_1",
"is_politically_exposed": true
},
"has_power_of_attorney": false,
"available_total_balance": 1000,
"has_judicial_concession": false,
"number_of_portabilities": 0,
"disbursement_bank_account": {
"bank_code": "341",
"account_digit": "6",
"account_branch": "0155",
"account_number": "000059923"
},
"has_entity_representation": false,
"social_benefit_max_balance": 2000,
"social_benefit_used_balance": 1000,
"benefit_quota_expiration_date": null,
"number_of_active_reservations": 0,
"number_of_suspended_reservations": 0,
"number_of_refinanced_reservations": 0,
"number_of_active_suspended_reservations": 3
}
}
Detalhamento de campos no webhook de sucesso
| Campo | Descrição | Valores |
|---|---|---|
| assistance_type | Tipo do benefício | Enumeradores |
| benefit_status | Status do beneficio | Enumeradores |
| has_entity_representation | Possui entidade de representação (não permite averbação) | True ou False |
| alimony_code | Classificador da Pensão alimentícia | not_payer, payer, benefit |
| has_judicial_concession | Benefício concedido por liminar | True ou False |
| has_power_of_attorney | Possui procurador? | True ou False |
| credit_type | Tipo de crédito - recebimento do benefício | Magnetic_card, checking_account |
| benefit_situation | Situação do benefício | Enumeradores |
| used_total_balance | Valor total comprometido em averbações de empréstimos, reservado para portabilidade, refinanciamento, alterações, RMC e RCC | Numérico |
| max_total_balance | Valor comprometido possível para a respectiva espécie do benefício | Numérico |
| available_total_balance | Valor total disponível para empréstimo, somando todas as modalidades (diferença entre max_total_balance e used_total_balance) | Numérico |
| benefit_quota_expiration_date | Data de extinção do benefício. A informação está disponível apenas para alguns benefícios de pensão por morte. | String ou nulo |
| block_type | Tipo de bloqueio do benefício | Enumeradores |
| politically_exposed.type | Pessoa politicamente exposta | Enumeradores |
| is_politically_exposed | Pessoa politicamente exposta | True ou False |
Webhook de bloqueio
Para os casos que o benefício está bloqueado
Webhook Body
{
"webhook_type": "social_security_balance_request",
"key": "<GUID balance_request_key>",
"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
"status": "blocked",
"data": {
"benefit_blocked": true,
"document_number": "12345678910",
"balance_request_date": "2025-12-01",
"block_date": "2025-11-17",
"assistance_type": "retirement_by_age",
"block_type": "blocked_by_benefitiary"
}
}
Detalhamento de campos no webhook de bloqueio
| Campo | Descrição | Valores |
|---|---|---|
| benefit_blocked | Status do bloqueio | True |
| balance_request_date | Data da consulta | String |
| block_date | Data do bloqueio | String ou nulo |
| block_type | Tipo de bloqueio | Enumeradores |
Webhook de falha
Em caso de falha na consulta da lista de benefícios
Webhook Body
{
"webhook_type": "social_security_balance_request",
"key": "<GUID balance_request_key>",
"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
"status": "failure",
"data": {
"enumerator": "not_found_legal_representative",
"description": "no legal representative for the beneficiary"
}
}
Detalhamento de campos no webhook de falha
| Campo | Descrição | Valores |
|---|---|---|
| enumerator | Retorno mapeado do código Dataprev | Enumeradores |
Simulando cenários de sucesso e insucesso na consulta de benefício em Sandbox:
A simulação de cenários é baseado no primeiro dígito do CPF informado na operação.
11.1. Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook.
11.2. Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo.
| Início do CPF | Enumerador | Descrição |
|---|---|---|
| 2 | inexistent_beneficiary | no beneficiary found |
Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado.
| Enumerador | Descrição |
|---|---|
| mock_error | Informed document number is not a valid mock on test environment |
11.3. O CPF 18166261553 simula, com sucesso (HTTP 200, sem erro), um benefício com margem consignável negativa (available_total_balance: -7.84). Use este CPF para testar a rejeição de novas operações quando o beneficiário já excedeu a margem disponível. Lista completa de CPFs e cenários mockados: Mocks (Sandbox).