Consulta da Lista de Benefícios
Consulta os benefícios do INSS de um CPF (POST /social_security/benefits_request), com a formalização do Termo de Autorização feita pelo parceiro. É o primeiro passo de qualquer operação INSS — crédito novo, refinanciamento ou portabilidade.
Próximo passo: Consulta de dados do benefício.
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.
Request
Caso 1: Titular do benefício é o assinante do Termo de Autorização.
Request Body
{
"document_number": "14950479032",
"authorization_term": {
"document_number": "14950479032",
"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"
}
}
}
}
Caso 2: Titular do benefício não é o assinante do Termo de Autorização (com representante legal).
Quando o titular do benefício não é o assinante do Termo de Autorização, os dados que preenchem o objeto signature.signer são os do representante legal, não os do titular.
Request Body
{
"document_number": "14950479032",
"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"
}
}
}
}
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.
"document_key": utilizar a GUID retornada no endpoint /upload
Ao invés da chave do documento pdf assinado no objeto "authorization_term.signed_object.document_key", também é possível enviar o texto corrido do Termo de Autorização, através do objeto "authorization_term.signed_object.raw_text".
Response
Response Body
{
"benefits_request_key": "<GUID DA CONSULTA DE BENEFÍCIO>",
"status": "pending_search"
}
Resposta quando o Termo de Autorização ainda está pendente de autorização:
Response Body
{
"benefits_request_key": "c9d2aa83-006b-4753-92ad-64411a7aa700",
"document_number": "18028522041",
"status": "pending_authorization",
"authorization_term": {
"authorization_term_key": "5a7b6489-8a47-4b61-a85a-6986b058fda6",
"status": "signed"
},
"status_events": [
{
"status": "pending_authorization",
"event_date": "2023-12-22T16:12:50"
}
]
}
Em caso de sucesso na consulta da lista de benefícios:
Webhooks
Webhook Body
{
"webhook_type": "social_security_benefits_request",
"key": "<GUID benefits_request_key>",
"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
"status": "success",
"data": [{
"benefit_number": "<No. DO BENEFÍCIO>",
"benefit_status": "inelegible",
"grant_date": "2023-06-13"
}]
}
| Campo | Descrição | Valores |
|---|---|---|
| benefit_number | Número do benefício | - |
| benefit_status | Status do beneficio | Enumeradores |
Em caso de falha na consulta da lista de benefícios
Webhook Body
{
"webhook_type": "social_security_benefits_request",
"key": "<GUID benefits_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 |