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.

Atenção

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.

Atenção!

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.

Reenvio de Webhooks

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.

POST

/private_payroll/employment_relationships_inquiry

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>"
            }
        }
    }
}

Atençã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

STATUS

202 Accepted

Response Body

{
    "employment_relationships_inquiry_key": "<UUID>",
    "employment_relationships_inquiry_status": "pending_inquiry"
}

info

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

WEBHOOK TYPE

laas.private_payroll.employment_relationships_inquiry_status_change

Retorno da consulta dos vínculos empregatícios:

STATUS

completed

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"
            }
        ]
    }
}

STATUS

failed

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"
    }
}

Aviso

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.

POST

/private_payroll/balance_inquiry

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>"
            }
        }
    }
}

Atenção

Response

STATUS

202 (Accepted)

Response Body

{
    "balance_inquiry_key": "<Balance Inquiry Key>",
    "balance_inquiry_status": "pending_inquiry"
}

info

Os possíveis valores para o enumerador balance_inquiry_status estão listados na seção Status das consultas de dados do trabalhador.

Webhooks

WEBHOOK TYPE

laas.private_payroll.balance_inquiry_status_change

Retorno da consulta de dados do trabalhador:

STATUS

completed

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"
            }
        ]
    }
}

STATUS

failed

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"
      }
    }
}

Aviso

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
Email	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

political_exposition

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

alert_type

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

contract_type

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

ENUMERADOR

employment_relationships_inquiry_status

ENUMERADOR

balance_inquiry_status

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.

Manual Consignado Privado - Consultas do trabalhador

1 - Consulta dos vínculos empregatícios do trabalhador:​

Request​

Response​

Webhooks​

2 - Consulta de dados do trabalhador:​

Request​

Response​

Webhooks​

Anexos​

Detalhamento do objeto authorization_term​

Detalhamento do webhook de consulta de dados​

Exposição política​

Detalhamento do objeto alerts​

Tipos de alerta​

Detalhamento do objeto legacy_loans​

Tipos de contrato legado​

Status das consultas de vínculos empregatícios e de dados do trabalhador​

1 - Consulta dos vínculos empregatícios do trabalhador:

Request

Response

Webhooks

2 - Consulta de dados do trabalhador:

Request

Response

Webhooks

Anexos

Detalhamento do objeto authorization_term

Detalhamento do webhook de consulta de dados

Exposição política

Detalhamento do objeto alerts

Tipos de alerta

Detalhamento do objeto legacy_loans

Tipos de contrato legado

Status das consultas de vínculos empregatícios e de dados do trabalhador