跳到主要内容

私人薪资抵押贷款手册 - 工人查询

导航

在私人薪资抵押贷款主动发行流程开始时，需要对工人进行两项主要查询：

  1. 雇佣关系查询：仅提供工人 CPF 即可执行。此操作返回工人的有效雇佣关系列表，以及每个关系的信贷操作资格。

  2. 工人数据查询：基于特定雇佣关系，提供在雇佣关系查询中获取的雇主文件号和工号。此操作返回所选雇佣关系的详细附加信息，包括个人数据、薪资抵押额度、雇佣关系历史及任何提醒。

注意

执行任何一项查询，都必须发送授权条款。 该条款必须基于借款人提供明确同意（opt-in）授权执行查询的证据而创建。 证据（如时间戳、IP 地址和会话标识符）必须包含在请求中，以确保流程的可追溯性和监管合规性。

这些查询连同授权条款是验证工人资格和在信贷操作正式化之前获取必要数据的基本步骤。

注意！

QI Tech 的 webhook 不应进行严格映射。 返回的 webhook payload 中可能包含额外字段。

重新发送 Webhook

您可以按照文档中的详细说明查询和重新发送 webhook：重新发送 Webhook。

1 - 工人雇佣关系查询：​

雇佣关系查询是一项异步操作。发送请求后，QI Tech 将在后台处理查询，并在完成后通过 webhook 返回结果。

Webhook 将发送到您环境中配置的 URL。

POST
/private_payroll/employment_relationships_inquiry

Request​

情况 1： 工人是授权条款的签署方。

Request Body
{
    "document_number": "12345678909",
    "authorization_term": {
        "signature": {
            "signer": {
                "name": "Nome do tomador",
                "email": "email_do_tomador@email.com",
                "phone": {
                    "number": "999999999",
                    "area_code": "11",
                    "country_code": "55"
                },
                "document_number": "12345678909"
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "2025-03-24T12:19:08Z",
                "ip_address": "255.255.255.255",
                "fingerprint": {},
                "session_id": "0b73fdb9-1b3b-4f09-9cf2-b775a1ce58d2"
            }
        }
    }
}

情况 2： 法定代理人是授权条款的签署方。

Request Body
{
    "document_number": "12345678909",
    "authorization_term": {
      "legal_representative_document_number": "32165498709",
        "signature": {
            "signer": {
                "name": "Nome do tomador",
                "email": "email_do_tomador@email.com",
                "phone": {
                    "number": "999999999",
                    "area_code": "11",
                    "country_code": "55"
                },
                "document_number": "12345678909"
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "2025-03-24T12:19:08Z",
                "ip_address": "255.255.255.255",
                "fingerprint": {},
                "session_id": "0b73fdb9-1b3b-4f09-9cf2-b775a1ce58d2"
            }
        }
    }
}
注意

有法定代理人的情况下，必须在 "legal_representative_document_number" 字段填写法定代理人的 CPF，"signer" 对象中的数据也应填写法定代理人的信息。

Response​

STATUS
202 Accepted
Response Body
{
    "employment_relationships_inquiry_key": "<UUID>",
    "employment_relationships_inquiry_status": "pending_inquiry"
}
信息

employment_relationships_inquiry_status 枚举的可能值列在雇佣关系查询状态部分。

Webhooks​

WEBHOOK TYPE
laas.private_payroll.employment_relationships_inquiry_status_change

雇佣关系查询返回结果：

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

要在沙盒环境中模拟失败，请使用以数字 2 开头的 CPF 进行查询。

2 - 工人数据查询：​

工人数据查询是一项异步操作。发送请求后，QI Tech 将在后台处理查询，并在完成后通过 webhook 返回结果。

Webhook 将发送到您环境中配置的 URL。

执行查询有两种可能的情况：

  1. 使用在雇佣关系查询中先前发送的授权条款
  2. 随查询一起发送新的授权条款

两种情况都需要提供在雇佣关系查询中获取的工人工号。

POST
/private_payroll/balance_inquiry

Request​

情况 1： 使用先前发送的授权条款进行工人数据查询。

Request Body
{
    "document_number": "<CPF FUNCIONÁRIO>",
    "registration_number": "<NÚMERO DE MATRÍCULA>",
    "employer_document_number": "<CNPJ EMPREGADOR>"
}

情况 2： 发送授权条款进行工人数据查询。

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

有法定代理人的情况下，必须在 "legal_representative_document_number" 字段填写法定代理人的 CPF，"signer" 对象中的数据也应填写法定代理人的信息。

Response​

STATUS
202 (Accepted)
Response Body
{
    "balance_inquiry_key": "<Balance Inquiry Key>",
    "balance_inquiry_status": "pending_inquiry"
}
信息

balance_inquiry_status 枚举的可能值列在工人数据查询状态部分。

Webhooks​

WEBHOOK TYPE
laas.private_payroll.balance_inquiry_status_change

工人数据查询返回结果：

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",
        "suspended_loans_count": 2,
        "block_type": "no_block",
        "blocked_at": null,
        "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"
      }
    }
}

雇佣关系被锁定时的返回结果：

STATUS
completed
Webhook Body
{
    "document_number": "99999999999",
    "registration_number": "abc",
    "employer_document_number": "12345678",
    "block_type": "blocked_by_the_worker",
    "blocked_at": "2025-12-11T10:00:00Z",
    "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"
      }
    }
}
警告

要在沙盒环境中模拟失败，请使用以数字 2 开头的 CPF 进行查询。

附件​

authorization_term 对象详情​

字段必填性描述
Name必填借款人姓名
Email可选借款人邮箱
Phone可选借款人电话
Document_number必填借款人 CPF
Authentication_type必填必须为 "opt-in"
Timestamp必填借款人接受的时间戳，必须为以下格式：2025-08-04T23:45:30Z
Ip_address必填用户会话 IP，可以是 IPv4（如：192.168.0.1）或 IPv6（如：2001:0db8:85a3:0000:0000:8a2e:0370:7334）
Fingerprint必填可发送有助于增强接受稳健性并有助于可追溯性的额外证据对象，虽为必填，但可发送空对象
Session_id必填用户会话的内部标识键，最小长度 10，最大长度 50

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

数据查询 webhook 详情​

字段描述
document_number借款人文件号
registration_number雇佣关系工号
employer_document_number雇主文件号（CNPJ 仅前 8 位数字）
name借款人姓名
gender借款人性别
birth_date借款人出生日期
worker_category_code符合 eSocial 网站标准的工人类别
eligible雇佣关系是否有资格发行薪资抵押信贷
available_margin_amount薪资抵押额度
base_margin_amount工资
total_due_amount借款人未偿余额
admission_date入职日期
termination_date离职日期
termination_reason_code符合 eSocial 网站标准的离职原因
political_exposition借款人政治曝光程度，可能的枚举值请见政治曝光表
employer_name雇主名称
mother_name借款人母亲姓名
nationality.description借款人国籍
nationality.code根据 ISO 3166 第 1 部分数字标准的国籍代码
occupation.description借款人根据巴西职业分类（CBO）的职业
occupation.codeCBO 2002 代码
economic_activity.description雇主根据国家经济活动分类（CNAE）的经济活动
economic_activity.codeCNAE 子类别 2.3 代码
ineligibility_reason雇佣关系不符合资格的原因
employer_activity_start_date雇主活动开始日期
legacy_loans由金融机构报告的有效贷款列表，字段详情请参阅 legacy_loans 对象详情表
alerts包含雇佣关系休假历史和离职通知的列表，字段详情请参阅 alerts 对象详情表
suspended_loans_count已暂停贷款数量
block_type雇佣关系锁定类型，可能的枚举值请见工资锁定表
blocked_at雇佣关系锁定日期

政治曝光​

ENUMERADOR
political_exposition
枚举值描述
not_exposed无政治曝光
level_1政治曝光级别 1
level_2政治曝光级别 2
not_informed无政治曝光信息

alerts 对象详情​

字段描述
alert_type提醒类型，可能的枚举值请见提醒类型表
reference_date事件参考日期
event_id事件标识符
leave_reason_code符合 eSocial 网站标准的休假原因
leave_start_date休假开始日期
leave_end_date休假结束日期
termination_reason_code符合 eSocial 网站标准的离职原因
termination_date雇佣关系离职日期
notice_period_start_date预告期开始日期
notice_period_end_date预告期结束日期

提醒类型​

ENUMERADOR
alert_type
枚举值描述
leave休假
termination离职预告

legacy_loans 对象详情​

字段描述
loan_amount放款金额
monthly_cet月 CET
monthly_rate月利率
contract_type合同类型，可能的枚举值请见遗留合同类型表
contract_number合同编号
contract_end_date合同结束日期
paid_installments已支付分期数
total_installments总分期数
installment_amount分期金额
contract_start_date合同开始日期
outstanding_balance未偿余额
last_update_timestamp最后更新日期
financial_institution_code报告贷款的金融机构代码

遗留合同类型​

ENUMERADOR
contract_type
枚举值描述
unsecured_non_consigned_loan无担保非薪资抵押贷款
loan_with_payroll_deductions含工资单扣款的贷款

雇佣关系查询和工人数据查询状态​

ENUMERADOR
employment_relationships_inquiry_status
ENUMERADOR
balance_inquiry_status
状态描述
pending_authorization授权数据已发送，待处理。
pending_inquiry查询已授权，待处理。
completed查询已成功完成。
failed查询失败。

雇佣关系锁定​

ENUMERADOR
block_type
枚举值描述
no_block雇佣关系未锁定
blocked_by_the_worker雇佣关系被员工锁定