跳到主要内容

薪资卡手册 - 发行

导航
API 开发中

该 API 仍处于开发阶段,因此本手册可能会有所变动。


福利查询

如需查询福利数据及福利列表,请访问 INSS 文档中的以下章节:

1. 查询受益人资格

资格查询可验证某个 CPF 是否符合 INSS 薪资/福利卡申领条件。该操作为同步操作,立即返回核验结果。

持有 CPF出生日期数据后,即可查询受益人资格。目前唯一进行的资格验证是受益人年龄是否在 18 至 65 岁之间。

Request

GET
/payroll_card_reservation/social_security/eligibility
Params
字段类型描述必填格式
document_numberstring受益人 CPF 号码11 位数字
birth_datedate出生日期YYYY-MM-DD

Response

STATUS
200 (OK)
Response 示例

符合资格:

{
"status": "eligible"
}

不符合资格 - 年龄超出范围:

{
"status": "not_eligible",
"error_description": "Age 66 is not within the eligible range (18-65 years)"
}
Response Body 详情
字段类型描述
statusstring资格状态(eligible/not_eligible)
error_descriptionstring不符合资格时的错误描述(可选)

2. 取款模拟与卡片额度

模拟计算可根据所提供的财务参数,计算可用取款金额和薪资卡额度。该操作适用于在签约前向受益人展示条件。

Request

POST
/payroll_card_reservation/social_security/simulation
Request Body
{
"financial": {
"salary_amount": 5000.00,
"number_of_installments": 96,
"monthly_interest_rate": 0.0246
},
"withdrawal": {
"disbursement_date": "2026-01-02",
"limit_days_to_disburse": 1,
"withdrawal_ratio": 0.7
},
"collateral": {
"collateral_type": "social_security_benefit_card"
}
}
Request Body 详情
字段类型描述格式必填
financialobject操作财务数据-
withdrawalobject取款数据-
collateralobject担保物数据-

Payload financial

字段类型描述格式必填
salary_amountnumber受益人薪资金额最小值: 1
number_of_installmentsnumber取款 CCB 分期数最小值: 1,最大值: 96
monthly_interest_ratenumber取款 CCB 月利率最小值: 0.01,最大值: 0.0246

Payload withdrawal

字段类型描述格式必填
disbursement_datedate取款 CCB 放款日期YYYY-MM-DD
limit_days_to_disbursenumber取款 CCB 放款最长天数最小值: 1,最大值: 10
withdrawal_rationumber用于取款的额度比例最小值: 0.5,最大值: 0.7否(默认: 0.7)

Payload collateral

字段类型描述格式必填
collateral_typestring卡片类型Enum: "social_security_benefit_card", "social_security_payroll_card"

Response

STATUS
201 (Created)
Response Body
{
"total_limit_amount": 8000,
"reservation_amount": 250,
"withdrawal": {
"withdrawal_amount": 5600,
"withdrawal_data": {
"prefixed_interest_rate": {
"interest_base": "calendar_days",
"annual_rate": 0.3386043084,
"monthly_rate": 0.0246,
"daily_rate": 0.0008104046
},
"disbursement_options": [
{
"disbursement_date": "2026-01-02",
"cet": 0.0261,
"annual_cet": 0.3618,
"total_iof": 193.55,
"disbursed_issue_amount": 5600,
"issue_amount": 5793.55,
"installments": [
{
"total_amount": 160.51,
"due_date": "2026-02-10",
"business_due_date": "2026-02-11",
"installment_number": 1
},
{
"total_amount": 160.51,
"due_date": "2026-03-10",
"business_due_date": "2026-03-11",
"installment_number": 2
},
{
"total_amount": 160.51,
"due_date": "2026-04-10",
"business_due_date": "2026-04-13",
"installment_number": 3
},
...
]
}
]
}
},
"payroll_card": {
"card_limit": 2400
}
}
Response Body 详情
字段类型描述
total_limit_amountnumber考虑取款和卡片后的可用总额度
reservation_amountnumber薪资卡预约金额
withdrawalobject取款数据
withdrawal.withdrawal_amountnumber计算得出的取款 CCB 放款金额
withdrawal.withdrawal_dataobject取款详细数据
payroll_cardobject薪资卡数据
payroll_card.card_limitnumber卡片计算得出的总额度

Payload withdrawal.withdrawal_data

字段类型描述
prefixed_interest_rateobject固定利率
disbursement_optionsarray可用放款选项

Payload prefixed_interest_rate

字段类型描述
daily_ratenumber日利率
interest_basestring利息计算基准
monthly_ratenumber月利率
annual_ratenumber年利率

Payload disbursement_options

字段类型描述
disbursement_datestring放款日期
cetnumber月综合实际利率
annual_cetnumber年综合实际利率
total_iofnumberIOF 总金额
disbursed_issue_amountnumber放款金额
issue_amountnumber发行金额
installmentsarray分期列表

Payload installments

字段类型描述
total_amountnumber分期总金额
due_datestring到期日期
installment_numbernumber分期编号

3. 创建取款操作并生成条款

创建取款操作将启动薪资卡签约流程。该操作创建卡片预约、生成所需文件,并返回用于跟踪流程的密钥。

POST
/payroll_card_reservation/social_security

Request

Request Body
{
"request_control_key": "150e8400-e29b-41d4-a716-446655440000",
"purchaser_document_number": "55566677000177",
"card_holder": {
"name": "Carlos Eduardo Lima",
"email": "carlos.lima@email.com",
"phone": {
"number": "654321098",
"area_code": "31",
"country_code": "055"
},
"gender": "male",
"address": {
"city": "Belo Horizonte",
"state": "MG",
"number": "789",
"street": "Rua das Palmeiras",
"complement": "Casa 3",
"postal_code": "30112000",
"neighborhood": "Savassi"
},
"birth_date": "1990-09-18",
"mother_name": "Fernanda Lima",
"nationality": "Brasileiro",
"document_number": "55566677788",
"document_identification": {
"document_identification_date": "2012-05-20",
"document_identification_type": "rg",
"document_identification_number": "555666777"
}
},
"related_parties": [
{
"name": "Pedro Costa",
"email": "pedro.costa@email.com",
"phone": {
"number": "765432109",
"area_code": "21",
"country_code": "055"
},
"address": {
"city": "Rio de Janeiro",
"state": "RJ",
"number": "789",
"street": "Rua Ipanema",
"complement": "Apto 12",
"postal_code": "22080001",
"neighborhood": "Ipanema"
},
"role_type": "issuer_legal_representative",
"person_type": "natural",
"is_pep": false,
"individual_document_number": "11122233344",
"birth_date": "1980-12-05",
"mother_name": "Lucia Costa",
"document_identification": {
"document_identification_date": "2017-01-14",
"document_identification_type": "rg",
"document_identification_number": "222333444"
}
}
],
"withdrawal": {
"disbursement_date": "2026-01-02",
"limit_days_to_disburse": 1,
"withdrawal_ratio": 0.7,
"contract_number": "PCR12345678",
"disbursement_bank_account": {
"name": "Carlos Eduardo Lima",
"bank_code": "104",
"account_digit": "3",
"branch_number": "5678",
"account_number": "987654321",
"document_number": "55566677788",
"transfer_method": "pix",
"account_type": "checking_account"
}
},
"financial": {
"salary_amount": 5000.00,
"number_of_installments": 96,
"monthly_interest_rate": 0.0246,
"emission_installments": 1
},
"collateral": {
"state": "MG",
"benefit_number": "5556667777",
"collateral_type": "social_security_benefit_card",
"subcorban_document_number": "12123456000101",
"assistance_type": "pension_by_death_rural_worker"
},
"credit_agent": {
"document_number": "44455566677",
"name": "Agente de Crédito Lima"
}
}
Request Body 详情
字段类型描述格式必填
request_control_keystring请求标识密钥UUID v4
purchaser_document_numberstring买方 CNPJ14 位数字
card_holderobject持卡人数据-
withdrawalobject取款数据-
financialobject操作财务数据-
collateralobject担保物数据-
credit_agentobject信贷代理人数据-
related_partiesarray相关方列表-

Payload card_holder

字段类型描述格式必填
namestring持卡人全名最少 1 个有效字符
emailstring持卡人电子邮件有效电子邮件格式
phoneobject电话数据-
genderstring性别Enum: "male", "female"
addressobject持卡人地址及卡片寄送地址-
birth_datedate出生日期YYYY-MM-DD
mother_namestring母亲姓名最少 1 个有效字符
nationalitystring国籍最少 1 个字符
document_numberstring持卡人 CPF11 位数字
document_identificationobject身份证件数据-
字段类型描述格式必填
namestring相关方姓名最少 1 个有效字符
emailstring相关方电子邮件有效电子邮件格式
phoneobject电话数据-
addressobject相关方地址-
role_typestring角色类型Enum: "issuer_legal_representative", "issuer_attorney"
person_typestring人员类型Enum: "natural"
is_pepboolean是否为政治敏感人士true/false
individual_document_numberstring相关方 CPF11 位数字
birth_datedate出生日期YYYY-MM-DD
mother_namestring母亲姓名最少 1 个有效字符
document_identificationobject身份证件数据-

Payload phone

字段类型描述格式必填
numberstring电话号码仅数字
area_codestring区号仅数字
country_codestring国家代码仅数字

Payload address

字段类型描述格式必填
citystring城市最少 1 个字符
statestring2 个字符
numberstring门牌号最少 1 个字符
streetstring街道最少 1 个字符
complementstring补充最少 1 个字符
postal_codestring邮政编码8 位数字
neighborhoodstring社区最少 1 个字符

Payload document_identification

字段类型描述格式必填
document_identification_datedate证件签发日期YYYY-MM-DD
document_identification_typestring证件类型Enum: "rg", "passport", "other"
document_identification_numberstring证件号码最少 1 个字符

Payload withdrawal

字段类型描述格式必填
disbursement_datedate放款日期YYYY-MM-DD
limit_days_to_disbursenumber放款最长天数最小值: 1,最大值: 10
contract_numberstring合同编号3 个大写字母 + 8 位数字
disbursement_bank_accountobject放款银行账户-

Payload disbursement_bank_account

字段类型描述格式必填
namestring账户持有人姓名最少 1 个有效字符
bank_codestring银行代码3 位数字
account_digitstring账户校验位1 位数字
branch_numberstring支行号仅数字
account_numberstring账户号码仅数字
document_numberstring持有人 CPF11 位数字
transfer_methodstring转账方式Enum: "pix", "ted"
account_typestring账户类型Enum: "checking_account","deposit_account","guaranteed_account","investment_account","payment_account","saving_account","salary_account"

Payload financial

字段类型描述格式必填
salary_amountnumber受益人薪资金额(福利总金额)最小值: 1
number_of_installmentsnumberCCB(取款和循环)分期数最小值: 1,最大值: 96
monthly_interest_ratenumberCCB(取款和循环)月利率最小值: 0.01,最大值: 0.0246
emission_installmentsnumber卡片发行费分期数(根据向受益人收集的信息填写)最小值: 1,最大值: 3

Payload collateral

字段类型描述格式必填
statestring2 个字符
benefit_numberstring福利编号最少 1 个字符
collateral_typestring担保物类型Enum: "social_security_benefit_card"(福利卡),"social_security_payroll_card"(薪资卡)
assistance_typestring福利类型Enum: 枚举值

Payload credit_agent

字段类型描述格式必填
document_numberstring信贷代理人 CPF11 或 14 位数字
namestring信贷代理人姓名最少 1 个有效字符

Response

STATUS
201 (Created)
Response Body
{
"request_control_key": "150e8400-e29b-41d4-a716-446655440000",
"payroll_card_type": "social_security_benefit_card",
"payroll_card_reservation_key": "72d63aea-15b6-402c-a18b-d12cd4619c9d",
"card_holder_document_number": "55566677788",
"identifier_number": "5556667777",
"total_limit_amount": 8000,
"reservation_amount": 250,
"withdrawal": {
"withdrawal_key": "56cfe7b7-ed6e-4212-8744-c9fcff309ec0",
"withdrawal_amount": 5600,
"credit_operation_key": null,
"withdrawal_status": "pending_signature",
"contract_number": "PCR12345678",
"withdrawal_data": {
"prefixed_interest_rate": {
"interest_base": "calendar_days",
"annual_rate": 0.3386043084,
"monthly_rate": 0.0246,
"daily_rate": 0.0008104046
},
"disbursement_options": [
{
"disbursement_date": "2026-01-02",
"cet": 0.0261,
"annual_cet": 0.3618,
"total_iof": 193.55,
"disbursed_issue_amount": 5600,
"issue_amount": 5793.55,
"installments": [
{
"total_amount": 160.51,
"due_date": "2026-02-10",
"business_due_date": "2026-02-11",
"installment_number": 1
},
{
"total_amount": 160.51,
"due_date": "2026-03-10",
"business_due_date": "2026-03-11",
"installment_number": 2
},
{
"total_amount": 160.51,
"due_date": "2026-04-10",
"business_due_date": "2026-04-13",
"installment_number": 3
},
...
]
}
]
},
"wallet_entry_key": null
},
"payroll_card": {
"payroll_card_key": "572650c7-67f6-4f73-8444-b9da72000057",
"payroll_card_status": "pending_issuance",
"card_key": null,
"payment_instrument_key": null,
"card_issuance_entry_key": null,
"card_issuance_entry_amount": 17.28,
"card_limit": 2400
},
"attached_documents": [
{
"document_key": "32f5e5e2-a15a-40af-9ddc-cddaba1966cf",
"document_type": "withdrawal_operation_term",
"document_certifier": "qi_sign",
"document_status": "pending_generation",
"document_url": null,
"document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
},
{
"document_key": "7767e30e-417e-4dd7-b061-bba722451d10",
"document_type": "payroll_card_term",
"document_certifier": "qi_sign",
"document_status": "pending_generation",
"document_url": null,
"document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
},
{
"document_key": "6c839b10-9558-4e6e-9f7d-d1e494cf6156",
"document_type": "payroll_card_consent_term",
"document_certifier": "qi_sign",
"document_status": "pending_generation",
"document_url": null,
"document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
}
],
"payroll_card_reservation_status": "pending_document_generation",
"wallet_key": null,
"reservation_contract_number": "PCR0000000822"
}
Response Body 详情
字段类型描述
request_control_keystring请求标识密钥
payroll_card_reservation_keystring薪资卡预约密钥
payroll_card_reservation_statusstring薪资卡预约状态
card_holder_document_numberstring持卡人 CPF
identifier_numberstring操作标识号
reservation_amountnumber薪资卡预约金额
reservation_contract_numberstringDataprev 批注合同编号
withdrawalobject取款数据
payroll_cardobject薪资卡数据
attached_documentsarray附件文件列表
payroll_card_typestring卡片类型(social_security_benefit_cardsocial_security_payroll_card
wallet_keystring已创建钱包的唯一密钥(UUID4)

Payload withdrawal

字段类型描述
withdrawal_keystring取款唯一密钥
contract_numberstring取款 CCB 合同编号
withdrawal_amountnumber计算得出的取款 CCB 放款金额
disbursement_datedate操作放款日期
withdrawal_statusstring取款状态
withdrawal_dataobject取款详细数据

Payload withdrawal_data

字段类型描述
prefixed_interest_rateobject固定利率
disbursement_optionsarray可用放款选项

Payload prefixed_interest_rate

字段类型描述
daily_ratenumber日利率
interest_basestring利息计算基准
monthly_ratenumber月利率
annual_ratenumber年利率

Payload disbursement_options

字段类型描述
disbursement_datestring放款日期
cetnumber月综合实际利率
annual_cetnumber年综合实际利率
total_iofnumberIOF 总金额
disbursed_issue_amountnumber放款金额
issue_amountnumber发行金额
installmentsarray分期列表

Payload installments

字段类型描述
total_amountnumber分期总金额
due_datestring到期日期
installment_numbernumber分期编号

Payload payroll_card

字段类型描述
payroll_card_keystring薪资卡唯一密钥
payroll_card_statusstring薪资卡状态
card_limitnumber卡片计算得出的总额度
card_issuance_entry_amountnumber卡片发行费金额

Payload attached_documents

字段类型描述
document_keystring文件唯一密钥
document_batch_keystring文件批次密钥
document_typestring文件类型
document_certifierstring文件认证机构
document_statusstring文件状态
document_urlstring文件 URL
signature_urlstring签名 URL


4. 发送附加文件

Dataprev 批注保证金后,预约状态更新为 pending_additional_documents_submission。要释放操作放款,必须发送附加文件(对于 INSS 薪资/福利卡产品,为签约确认视频)。

上传处理为异步操作。上传成功后将自动触发预约状态转换至 pending_additional_documents_validation,发送状态变更文件更新 Webhook,并触发文件验证。

附加文件被拒绝与重新提交

如果附加文件在系统验证中被拒绝,预约将返回至 pending_additional_documents_submission 状态,可通过同一接口重新提交附加文件。在系统分析批准/拒绝之前,不可重新提交附加文件,且每个预约和文件类型的分析次数上限为 5 次。

注意:放款触发条件

发送附加文件及系统随后的批准视为信贷操作的授权。文件验证成功后,操作将自动进入 pending_withdrawal_disbursement 状态(通过 Webhook 通知客户),并在受益人账户执行放款,无需额外审批步骤

Request

POST
/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/additional_documents
Params
字段类型描述必填
payroll_card_reservation_keystring预约唯一密钥(UUID)
Request Body
{
"documents": [
{
"document_type": "payroll_card_confirmation_video",
"document_url": "https://download.samplelib.com/mp4/sample-5s.mp4"
}
]
}
Request Body 详情
字段类型描述必填
documentsarray待附加文件列表

Payload documents

字段类型描述格式必填
document_typestring文件类型Enum: "payroll_card_confirmation_video"
document_urlstring视频文件公开下载链接有效 URL
视频 URL

请确保发送的 URL 可被外部用户访问,以便我们将文件上传至 QI 内部数据库。

  • 支持的文件格式:.mp4
  • 最大文件大小:256MB

Response

STATUS
200 (OK)

请求已成功接收,文件将异步处理。

{
"attached_documents": [
{
"document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
"document_type": "payroll_card_confirmation_video",
"document_certifier": "electronic_client_side",
"document_status": "pending_generation",
"document_url": ""
}
],
}

5. 取款付款重新提交

如因数据不正确导致付款未能处理,可通过以下接口调整银行账户信息进行重新提交:

PATCH
/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/disbursement_account

Request

Request Body
{
"disbursement_bank_account": {
"name": "Carlos Eduardo Lima",
"bank_code": "001",
"account_digit": "3",
"branch_number": "5678",
"account_number": "987654321",
"document_number": "55566677788",
"transfer_method": "pix",
"account_type": "checking_account"
}
}
Request Body 详情
字段类型描述格式必填
disbursement_bank_accountobject放款银行账户-

Payload disbursement_bank_account

字段类型描述格式必填
namestring账户持有人姓名最少 1 个有效字符
bank_codestring银行代码3 位数字
account_digitstring账户校验位1 位数字
branch_numberstring支行号仅数字
account_numberstring账户号码仅数字
document_numberstring持有人 CPF11 位数字
transfer_methodstring转账方式Enum: "pix", "ted"
account_typestring账户类型Enum: "checking_account","deposit_account","guaranteed_account","investment_account","payment_account","saving_account","salary_account"

Response

STATUS
200 (OK)

6. 附录

同质化测试环境(Mock)

为方便在 Sandbox 环境中进行集成测试,系统根据创建 payload 中发送的受益人 CPF 首位数字模拟不同行为。

使用下表模拟成功和错误场景:

CPF 首位数字场景内部行为最终结果(客户)
1理想流程(完整)签名成功
入网成功
批注(Dataprev)成功
卡片已发行
(状态:card_issued
2Dataprev 查询错误签名成功
入网成功
福利查询失败
预约已取消
(状态:canceled
+ 发送状态 Webhook
(状态:canceled
3Dataprev 批注错误签名成功
入网成功
保证金批注/预约失败
预约已取消
(状态:canceled
+ 发送状态 Webhook
(状态:canceled
4地址错误签名成功
入网成功(地址不符)
批注(Dataprev)成功
卡片已发行
(状态:card_issued
+ 发送地址更新 Webhook
5入网被拒签名成功
入网/KYC 被拒
预约已取消
(状态:canceled
+ 发送状态 Webhook
(状态:canceled
6不符合资格(年龄 > 65)签名成功
入网成功(返回年龄超过 65 岁)
预约已取消
(状态:canceled
+ 发送状态 Webhook
(状态:canceled
7不符合资格(年龄 < 18)签名成功
入网成功(返回年龄低于 18 岁)
预约已取消
(状态:canceled
+ 发送状态 Webhook
(状态:canceled
8Teimosinha(重试)签名成功
入网成功
批注(Dataprev)临时失败
等待释放
(状态:pending_reservation
+ 发送 Collateral Webhook
提示

要测试理想流程,请确保使用以 1 开头的 CPF(例如:123.456.789-00)且为有效 CPF(校验位计算正确)。

提示

成功 Mock 配置为模拟最高 R$10,000.00 的福利。如果使用超过此金额的福利值,系统将在批注时返回保证金超额错误,取消预约。


福利类型表

代码福利类型
1pension_by_death_rural_worker
2pension_by_death_accident_rural_worker
3pension_by_death_rural_employer
4retirement_invalidity_rural_emploee
5retirement_invalidity_accident_rural_worker
6retirement_invalidity_rural_employer
7retirement_by_eldness_rural_worker
8retirement_by_age_rural_employer
9complement_by_work_accident_rural_worker
11support_invalidity_rural_worker
12support_by_age_rural_worker
13aid_sickness_rural_worker
15aid_time_off_rural_worker
16aid_federal
17international_agreement
18inclusion_benefit
19pension_student_law7004
20pension_by_death_diplomat
21pension_by_death
22pension_by_death_statute
23pension_by_death_veteran
24pension_special_institutional_act
25aid_time_off
26pension_by_death_special_law593
27pension_by_death_federal_emploee
28pension_by_death_general_regime_law20465
29pension_by_death_marine_veteran
30monthly_income_lifetime_invalidity
31aid_sickness
32retirement_invalidity_social_security
33retirement_invalidity_aeronautic
34retirement_invalidity_marine_law1756
35aid_sickness_veteran
36aid_social_security_accident
37retirement_capin_extra_emploee
38retirement_federal_extra_emploee
39aid_invalidity_student_law7004
40monthly_income_lifetime_by_age_upper70_law6179
41retirement_by_age
42retirement_by_contribution_time
43retirement_by_time_of_service_veteran
44retirement_special_aeronautic
45retirement_by_time_of_service_journalist
46retirement_special
47allowance_25
48allowance_20
49retirement_ordinary
50aid_sickness_extinct_basic_plan
51retirement_invalidity_extinct_basic_plan
52retirement_by_age_extinct_basic_plan
53aid_time_off_extinct_basic_plan
54pension_indemnity_federal
55pension_by_death_extinct_basic_plan
56pension_lifetime_syndrome_thalidomide
57retirement_by_teacher_labor_time
58retirement_anisty
59pension_by_death_amnesty
60indemnity
61aid_birth
62aid_funeral
63aid_funeral_rural_worker
64aid_funeral_rural_employer
65savings_special_autarchy
67savings_mandatory_ipase_law5128
68savings_special_retirement_ps_affiliated_upper60
69savings_student_law7004
70restitution
71monthly_income
72retirement_by_time_of_service_law1756
73monthly_income_family_statute
74complement_pension_federal
75complement_retirement_federal
76monthly_income_statute
77monthly_income_sinpas_family_statute
78retirement_by_age_law1756
79advantage
80monthly_income_maternity
81compulsory_retirement
82retirement_by_time_of_service_sasse
83retirement_invalidity_ex_sasse
84pension_by_death_sasse
85pension_lifetime_rubber_tapper_law7986
86pension_lifetime_rubber_tapper_dependent_law7986
87continuous_aid_physical_disabilities
88continuous_aid_eldness
89pension_special_hemodialysis_victim_caruaru
90medic_assistency_work_accident
91aid_sickness_by_work_accident
92retirement_invalidity_work_accident
93pension_by_death_work_accident
94aid_work_accident
95aid_additional_work_accident
96pension_special_leprosy_law11520
97savings_by_death_work_accident
98aid_longshoreman
99time_off_15