Manual Consignado Privado - Consultas do trabalhador
No início do fluxo ativo de emissão de uma dívida de consignado privado, é necessário realizar duas consultas principais relacionadas ao trabalhador:
-
Consulta de vínculos empregatícios: realizada informando apenas o CPF do trabalhador. Essa operação retorna a lista de vínculos ativos do trabalhador, juntamente com a elegibilidade de cada um para operações de crédito.
-
Consulta de dados do trabalhador: realizada com base em um vínculo específico, informando o número de documento do empregador e o número de matrícula obtidos na consulta de vínculos. Essa operação retorna informações adicionais detalhadas sobre o vínculo selecionado, incluindo dados pessoais, margem consignável, histórico do vínculo e eventuais alertas.
Para realizar qualquer uma dessas consultas, é obrigatório enviar um Termo de autorização. Esse termo deve ser criado a partir da coleta de evidências de que o tomador forneceu um aceite expresso (opt-in) autorizando a execução das consultas. As evidências — como timestamp, endereço IP e identificador de sessão — devem ser incluídas na requisição para garantir a rastreabilidade e conformidade regulatória do processo.
Essas consultas, juntamente com o Termo de autorização, são etapas fundamentais para validar a elegibilidade do trabalhador e obter os dados necessários antes da formalização da operação de crédito.
Os webhooks da QI Tech não devem ser mapeados de forma estrita. 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.
1 - Consulta dos vínculos empregatícios do trabalhador:
A consulta de vínculos empregatícios é uma operação assíncrona. Ao enviar a requisição, a QI Tech processará a consulta em background e retornará o resultado através de um webhook quando finalizada.
O webhook será enviado para a URL configurada no seu ambiente.
Request
Caso 1: O trabalhador é o assinante do Termo de autorização.
Request Body
{
"document_number": "<CPF FUNCIONÁRIO>",
"authorization_term": {
"signature": {
"signer": {
"name": "<NOME DO ASSINANTE>",
"email": "<EMAIL DO ASSINANTE>",
"phone": {
"number": "<NUMERO DO ASSINANTE>",
"area_code": "<DDD DO ASSINANTE>",
"country_code": "55"
},
"document_number": "<CPF DO ASSINANTE>"
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "<DATA E HORA DA ASSINATURA>",
"ip_address": "<IP DO ASSINANTE>",
"fingerprint": {},
"session_id": "<ID DA SESSÃO DO ASSINANTE>"
}
}
}
}
Caso 2: O representante legal é o assinante do Termo de autorização.
Request Body
{
"document_number": "<CPF FUNCIONÁRIO>",
"authorization_term": {
"legal_representative_document_number": "<CPF DO ASSINANTE>",
"signature": {
"signer": {
"name": "<NOME DO ASSINANTE>",
"email": "<EMAIL DO ASSINANTE>",
"phone": {
"number": "<NUMERO DO ASSINANTE>",
"area_code": "<DDD DO ASSINANTE>",
"country_code": "55"
},
"document_number": "<CPF DO ASSINANTE>"
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "<DATA E HORA DA ASSINATURA>",
"ip_address": "<IP DO ASSINANTE>",
"fingerprint": {},
"session_id": "<ID DA SESSÃO DO ASSINANTE>"
}
}
}
}
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
{
"employment_relationships_inquiry_key": "<UUID>",
"employment_relationships_inquiry_status": "pending_inquiry"
}
Os possíveis valores para o enumerador employment_relationships_inquiry_status estão listados na seção Status das consultas de vínculos empregatícios.
Webhooks
Retorno da consulta dos vínculos empregatícios:
Webhook Body
{
"key": "<Employment Relationships Inquiry Key>",
"status": "completed",
"webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
"event_datetime": "2025-03-24T15:28:31Z",
"data": {
"authorization_term": {
"status": "authorized",
"authorization_term_key": "<UUID>",
"signed_at": "2025-03-24T12:19:08Z",
"expiration_date": "2025-04-24"
},
"employment_relationships": [
{
"eligible": true,
"document_number": "47812365409",
"registration_number": "99999999999-A",
"employer_document_type": "cpf",
"employer_document_number": "34848037034"
},
{
"eligible": false,
"document_number": "47812365409",
"registration_number": "11111111111-B",
"employer_document_type": "cnpj",
"employer_document_number": "33296860000173"
}
]
}
}
Webhook Body
{
"key": "<Employment Relationships Inquiry Key>",
"status": "failed",
"webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
"event_datetime": "2025-03-24T15:28:31Z",
"data": {
"enumerator": "ineligible_worker_cpf",
"description": "CPF not found in database or worker CPF ineligible",
"translation": "CPF não encontrado na base ou CPF do trabalhador inelegível"
}
}
Para simular uma falha em ambiente de sandbox, realize uma consulta com um CPF iniciado com o dígito 2.
2 - Consulta de dados do trabalhador:
A consulta de dados do trabalhador é uma operação assíncrona. Ao enviar a requisição, a QI Tech irá processar a consulta em background e retornará o resultado através de um webhook quando finalizada.
O webhook será enviado para a URL configurada no seu ambiente.
Existem dois cenários possíveis para realizar a consulta:
- Utilizando um Termo de autorização previamente enviado na consulta de vínculos empregatícios
- Enviando um novo Termo de autorização junto com a consulta
Em ambos os casos, é necessário informar o número de matrícula do trabalhador obtido na consulta de vínculos empregatícios.
Request
Caso 1: Consulta de dados do trabalhador com o Termo de autorização previamente enviado.
Request Body
{
"document_number": "<CPF FUNCIONÁRIO>",
"registration_number": "<NÚMERO DE MATRÍCULA>",
"employer_document_number": "<CNPJ EMPREGADOR>"
}
Caso 2: Consulta de dados do trabalhador com envio do Termo de autorização.
Request Body
{
"document_number": "<CPF FUNCIONÁRIO>",
"registration_number": "<NÚMERO DE MATRÍCULA>",
"employer_document_number": "<CNPJ EMPREGADOR>",
"authorization_term": {
"legal_representative_document_number": "<CPF DO REPRESENTANTE LEGAL>", // Caso aplicável
"signature": {
"signer": {
"name": "<NOME DO ASSINANTE>",
"email": "<EMAIL DO ASSINANTE>",
"phone": {
"number": "<NUMERO DO ASSINANTE>",
"area_code": "<DDD DO ASSINANTE>",
"country_code": "55"
},
"document_number": "<CPF DO ASSINANTE>"
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "<DATA E HORA DA ASSINATURA>",
"ip_address": "<IP DO ASSINANTE>",
"fingerprint": {},
"session_id": "<ID DA SESSÃO DO ASSINANTE>"
}
}
}
}
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_inquiry_key": "<Balance Inquiry Key>",
"balance_inquiry_status": "pending_inquiry"
}
Os possíveis valores para o enumerador balance_inquiry_status estão listados na seção Status das consultas de dados do trabalhador.
Webhooks
Retorno da consulta de dados do trabalhador:
Webhook Body
{
"key": "<Balance Inquiry Key>",
"status": "completed",
"webhook_type": "laas.private_payroll.balance_inquiry_status_change",
"event_datetime": "2024-02-21T14:30:25Z",
"data": {
"document_number": "99999999999",
"registration_number": "99999999999-A",
"employer_document_number": "99999999999962",
"name": "JOÃO SILVA",
"gender": "male",
"birth_date": "1985-07-20",
"worker_category_code": 101,
"eligible": true,
"available_margin_amount": 5000.00,
"base_margin_amount": 4500.00,
"total_due_amount": 8207.54,
"admission_date": "2020-03-15",
"termination_date": null,
"termination_reason_code": null,
"political_exposition": "not_exposed",
"employer_name": "EMPRESA XYZ LTDA",
"mother_name": "MARIA DA SILVA",
"nationality": {
"code": 76,
"description": "BRASIL"
},
"occupation": {
"code": 724325,
"description": "SOLDADOR ELETRICO"
},
"economic_activity": {
"code": 2833000,
"description": "FABRICACAO DE MAQUINAS E EQUIPAMENTOS PARA A AGRICULTURA E PECUARIA, PECAS E ACESSORIOS, EXCETO PARA IRRIGACAO"
},
"ineligibility_reason": "not_informed",
"employer_activity_start_date": "2010-05-12",
"legacy_loans": [],
"alerts": [
{
"alert_type": "leave",
"reference_date": "2025-02-11",
"event_id": 123456,
"leave_reason_code": 3,
"leave_start_date": "2025-02-11",
"leave_end_date": "2025-03-11"
},
{
"alert_type": "termination",
"reference_date": "2025-02-11",
"event_id": 789012,
"termination_reason_code": 1,
"termination_date": "2025-02-11",
"notice_period_start_date": "2025-01-11",
"notice_period_end_date": "2025-02-11"
}
]
}
}
Webhook Body
{
"key": "<Balance Inquiry Key>",
"status": "failed",
"webhook_type": "laas.private_payroll.balance_inquiry_status_change",
"event_datetime": "2024-02-21T14:30:25Z",
"data": {
"authorization_term": {
"status": "authorized",
"signed_at": "2025-08-10T17:42:05Z",
"expiration_date": "2025-09-09",
"authorization_term_key": "4444cc5b-9c60-473f-8fe4-6c43b855be6d"
}
}
}
Para simular uma falha em ambiente de sandbox, realize uma consulta com um CPF iniciado com o dígito 2.
Anexos
Detalhamento do objeto authorization_term
| Campo | Obrigatoriedade | Descrição |
|---|---|---|
| Name | Obrigatório | Nome do tomador |
| Opcional | Email do tomador | |
| Phone | Opcional | Telefone do tomador |
| Document_number | Obrigatório | CPF do tomador |
| Authentication_type | Obrigatório | Obrigatoriamente "opt-in" |
| Timestamp | Obrigatório | Timestamp do aceite do tomador, obrigatoriamente no formato: 2025-08-04T23:45:30Z |
| Ip_address | Obrigatório | IP da sessão do usuário, seja em IPv4 (ex: 192.168.0.1) ou IPv6 (ex: 2001:0db8:85a3:0000:0000:8a2e:0370:7334) |
| Fingerprint | Obrigatório | Objeto onde podem ser enviadas evidências adicionais que contribuam com a robustez do aceite e que auxiliem na rastreabilidade, apesar de obrigatório, pode ser enviado um objeto nulo |
| Session_id | Obrigatório | Chave identificadora interna da sessão do usuário, tamanho mínimo 10 e máximo 50 |
Exemplos de campos do objeto fingerprint
{
"fingerprint_id": "4c188fc4-2cb4-48cc-9236-7df953570638",
"lat": "-15.82891",
"long": "-48.12751",
"name": "ALBERTO PEREIRA",
"device": "Web",
"browser": "Chrome",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/037.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/037.36",
"browser_version": "120.0.0.0"
}
Detalhamento do webhook de consulta de dados
| Campo | Descrição |
|---|---|
| document_number | Documento do tomador |
| registration_number | Número de registro do vínculo empregatício |
| employer_document_number | Número de documento do empregador (no caso de CNPJ somente os 8 primeiros dígitos) |
| name | Nome do tomador |
| gender | Gênero do tomador |
| birth_date | Data de nascimento do tomador |
| worker_category_code | Categoria do trabalhador em conformidade com o site do eSocial |
| eligible | Eligibilidade do vínculo para emissão de crédito consignado |
| available_margin_amount | Margem consignável |
| base_margin_amount | Salário |
| total_due_amount | Saldo devedor do tomador |
| admission_date | Data de admissão |
| termination_date | Data de desligamento |
| termination_reason_code | Motivo do desligamento em conformidade com o site do eSocial |
| political_exposition | Nível de exposição política do tomador, consulte os possíveis enumeradores na tabela Exposição política |
| employer_name | Nome do empregador |
| mother_name | Nome da mãe do tomador |
| nationality.description | Nacionalidade do tomador |
| nationality.code | Código da nacionalidade to tomador segundo o padrão numérico da parte 1 da norma ISO 3166 |
| occupation.description | Ocupação do tomador segundo a Clasificação Brasileira de Ocupações (CBO) |
| occupation.code | Código segundo a CBO 2002 |
| economic_activity.description | Atividade econômica do empregador segundo a Classificação Nacional de Atividades Econômicas (CNAE) |
| economic_activity.code | Código segundo a CNAE Subclasses 2.3 |
| ineligibility_reason | Motivo da inelegibilidade do vínculo |
| employer_activity_start_date | Data de início da atividade do empregador |
| legacy_loans | Lista de empréstimos ativos informados pelas IFs, para detalhamento dos campos consulte a tabela Detalhamento do objeto legacy_loans |
| alerts | Lista com histórico de afastamentos e avisos de desligamento do vínculo, para detalhamento dos campos consulte a tabela Detalhamento do objeto alerts |
Exposição política
| Enumerador | Descrição |
|---|---|
| not_exposed | Pessoa não exposta politicamente |
| level_1 | Pessoa exposta politicamente nível 1 |
| level_2 | Pessoa exposta politicamente nível 2 |
| not_informed | Não há informação sobre a exposição política |
Detalhamento do objeto alerts
| Campo | Descrição |
|---|---|
| alert_type | Tipo de alerta, consulte os possíveis enumeradores na tabela Tipos de alerta |
| reference_date | Data de referência do evento |
| event_id | Identificador do evento |
| leave_reason_code | Motivo do afastamento em conformidade com o site do eSocial |
| leave_start_date | Data de início do afastamento |
| leave_end_date | Data de término do afastamento |
| termination_reason_code | Motivo do desligamento em conformidade com o site do eSocial |
| termination_date | Data de desligamento do vínculo |
| notice_period_start_date | Data de início do período de aviso prévio |
| notice_period_end_date | Data de término do período de aviso prévio |
Tipos de alerta
| Enumerador | Descrição |
|---|---|
| leave | Afastamento |
| termination | Aviso prévio de desligamento |
Detalhamento do objeto legacy_loans
| Campo | Descrição |
|---|---|
| loan_amount | Valor desembolsado |
| monthly_cet | CET mensal |
| monthly_rate | Taxa mensal |
| contract_type | Tipo de contrato, consulte os possíveis enumeradores na tabela Tipos de contrato legado |
| contract_number | Número de contrato |
| contract_end_date | Data de término do contrato |
| paid_installments | Quantidade de parcelas pagas |
| total_installments | Quantidade total de parcelas |
| installment_amount | Valor de parcela |
| contract_start_date | Data de início do contrato |
| outstanding_balance | Saldo devedor |
| last_update_timestamp | Data da última atualização |
| financial_institution_code | Código da IF que informou o empréstimo |
Tipos de contrato legado
| Enumerador | Descrição |
|---|---|
| unsecured_non_consigned_loan | Empréstimo não consignado sem garantia |
| loan_with_payroll_deductions | Empréstimo com descontos em folha de pagamento |
Status das consultas de vínculos empregatícios e de dados do trabalhador
| Status | Descrição |
|---|---|
| pending_authorization | Os dados de autorização foram enviados e estão pendentes de processamento. |
| pending_inquiry | A consulta está autorizada e pendente de ser processada. |
| completed | A consulta foi concluída com sucesso. |
| failed | A consulta falhou. |