薪资卡手册 - 跟踪查询

导航

API 开发中

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

1. 查询薪资卡预留

通过预留密钥（payroll_card_reservation_key）或请求控制密钥（request_control_key）查询特定预留的详细信息。返回包含预留详情的单个对象。

GET

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

GET

/payroll_card_reservation/social_security/request_control_key/[REQUEST-CONTROL-KEY]

Query Params

Query Params

字段	类型	描述
retrieve_document_urls	bool	是否返回某些文档的 URL。默认设置为 False。

参数 retrieve_document_urls

启用该参数可能会导致请求延迟。仅在必要时使用。

目前，只有 benefit.policy_document_url 字段受此参数影响，但其他 URL 字段（如 attached_documents.document_url 和 attached_documents.signature_url）将来也会依赖此参数。

受影响的字段（当前和未来）均以 (*) 标记。

Response

Response Body

{
  "request_control_key": "550e8400-e29b-41d4-a716-446655440000",
  "payroll_card_reservation_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payroll_card_reservation_status": "pending_document_generation",
  "card_holder_document_number": "12345678901",
  "identifier_number": "1234567890",
  "total_limit_amount": 8000.00,
  "reservation_amount": 250.00,
  "reservation_contract_number": "PCR0123456789",
  "wallet_key": null,
  "payroll_card_type": "social_security_payroll_card",
  "signature_url": "https://sandbox.sign.qitech.com.br/s/teste",
  "signature_data": {
      "document_similarity_score": 1,
      "similarity_score": 0.75,
      "biometry_analysis_reference": "internal",
  },
  "withdrawal": {
    "withdrawal_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
    "withdrawal_amount": 5600.00,
    "withdrawal_status": "waiting_signature",
    "contract_number": "PCR12345678",
    "disbursement_date": "2025-08-08",
    "withdrawal_data": {
      "disbursement_options": [
        {
          "disbursement_date": "2025-08-08",
          "cet": 0.0262,
          "annual_cet": 0.3643,
          "issue_amount": 5827.36,
          "prefixed_interest_rate": {
            "daily_rate": 0.0008104046,
            "interest_base": "calendar_days",
            "monthly_rate": 0.0246,
            "annual_rate": 0.3386043084
          },
          "installments": [
            {
              "total_amount": 152.5,
              "due_date": "2025-10-10",
              "installment_number": 1
            },
            {
              "total_amount": 152.5,
              "due_date": "2025-11-10",
              "installment_number": 2
            },
            {
              "total_amount": 152.5,
              "due_date": "2025-12-10",
              "installment_number": 3
            }
          ]
        }
      ]
    }
  },
  "payroll_card": {
    "payroll_card_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
    "payroll_card_status": "pending_issuance",
    "card_limit": 2400.00,
    "card_issuance_entry_amount": 17.28
  },
  "attached_documents": [
    {
      "document_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "withdrawal_operation_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    },
    {
      "document_key": "f6g7h8i9-j0k1-2345-fghi-678901234567",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "payroll_card_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    },
    {
      "document_key": "925c0a62-ef98-4891-909b-9955a87ccefb",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "payroll_card_consent_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    }
  ],
  "benefit": {
    "benefit_key": "0b80d313-2ade-4a28-be58-38b9219c2b8c",
    "card_insurance_key": "0151934c-b219-458f-98a3-8b0f85c70307",
    "status": "active",
    "due_date": "2036-02-18",
    "policy_document_key": "6363eb63-2e85-4786-bc03-8c1ddd8e2be2",
    "policy_document_url": "https://example.com/policy.pdf"
  }
}

Response Body Details

字段	类型	描述
request_control_key	string	请求识别密钥
payroll_card_reservation_key	string	薪资卡预留密钥
payroll_card_reservation_status	string	薪资卡预留状态
card_holder_document_number	string	持卡人 CPF
identifier_number	string	操作识别号
reservation_amount	number	薪资卡预留金额
reservation_contract_number	string	Dataprev 批注合同号
withdrawal	object	提款数据
payroll_card	object	薪资卡数据
attached_documents	array	附件文档列表
payroll_card_type	string	卡类型（`social_security_benefit_card` 或 `social_security_payroll_card`）
wallet_key	string	创建的钱包唯一密钥（UUID4）
signature_url	string	预留合同签署 URL（仅在生成签署链接后存在于 payload 中）
signature_data	object	签署时收集的生物特征数据（仅在文件签署后存在于 payload 中）
benefit	object	与卡关联的保险/福利数据（仅在卡发行后存在于 payload 中）

Payload withdrawal

字段	类型	描述
withdrawal_key	string	提款唯一密钥
contract_number	string	提款 CCB 合同号
withdrawal_amount	number	提款 CCB 计算的放款金额
disbursement_date	date	操作放款日期
withdrawal_status	string	提款状态
withdrawal_data	object	提款详细数据

Payload withdrawal_data

字段	类型	描述
prefixed_interest_rate	object	固定利率
disbursement_options	array	可用放款选项

Payload prefixed_interest_rate

字段	类型	描述
daily_rate	number	日利率
interest_base	string	利息计算基础
monthly_rate	number	月利率
annual_rate	number	年利率

Payload disbursement_options

字段	类型	描述
disbursement_date	string	放款日期
cet	number	月总有效成本
annual_cet	number	年总有效成本
total_iof	number	IOF 总金额
disbursed_issue_amount	number	放款金额
issue_amount	number	发行金额
installments	array	分期付款列表

Payload installments

字段	类型	描述
total_amount	number	分期付款总额
due_date	string	到期日期
installment_number	number	分期序号

Payload payroll_card

字段	类型	描述
payroll_card_key	string	薪资卡唯一密钥
payroll_card_status	string	薪资卡状态
card_limit	number	卡的计算总额度
card_issuance_entry_amount	number	卡发行费金额

Payload attached_documents

字段	类型	描述
document_key	string	文档唯一密钥
document_batch_key	string	文档批次密钥
document_type	string	文档类型
document_certifier	string	文档认证机构
document_status	string	文档状态
document_url (*)	string	文档 URL
signature_url (*)	string	签署 URL

Payload signature_data

字段	类型	描述
document_similarity_score	number	签署人与提交文件之间的生物特征相似度评分（0-1）
similarity_score	number	签署人与人脸库中找到的参考之间的生物特征相似度评分（0-1）
biometry_analysis_reference	string	用于计算生物特征相似度评分的人脸来源库

Payload benefit

字段	类型	描述
benefit_key	string	福利唯一密钥（UUID）
status	string	保险发行状态（`created`、`pending_emission`、`active`、`canceled` 或 `inactive`）
policy_document_key	string	保单文件唯一密钥（UUID）
policy_document_url (*)	string	保险保单文件 URL

2. 按 CPF 查询薪资卡预留

查询特定 CPF 的有效预留。返回 payroll_card_reservations 属性中的对象列表。

GET

/payroll_card_reservation/social_security/card_holder_document_number/[CARD-HOLDER-DOCUMENT-NUMBER]

Response

Response Body

{
   "payroll_card_reservations": [
      {
        "request_control_key": "d3bc353e-d612-4029-9d77-4dca9171c3b5",
        "payroll_card_reservation_key": "5fb9d810-be74-4d26-959d-c75d10834e93",
        "payroll_card_reservation_status": "card_issued",
        "card_holder_document_number": "12345678901",
        "identifier_number": "1234567890",
        "total_limit_amount": 8000.00,
        "reservation_amount": 250.00,
        "reservation_contract_number": "PCR0123456789",
        "wallet_key": "298e4d37-0f20-4aed-ad66-016f8487afba",
        "payroll_card_type": "social_security_payroll_card",
        "card_holder": {
          "email": "joao.teste@example.com",
          "phone": {
            "number": "352141677",
            "area_code": "11",
            "country_code": "055"
          },
          "address": {
            "city": "Belo Horizonte",
            "state": "MG",
            "number": "7889",
            "street": "Rua Santos",
            "complement": "Apto 243",
            "postal_code": "30112000",
            "neighborhood": "Centro"
          }
        },
        "attached_documents": [
          {
              "document_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
              "document_type": "withdrawal_operation_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
              "document_type": "payroll_card_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b098074a-7cba-4b67-81e1-8d587185504b",
              "document_type": "payroll_card_consent_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b1c3e915-6707-49f5-85a9-398ef997fdad",
              "document_type": "selfie",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/selfie.jpeg"
          },
          {
              "document_key": "5769a335-a2ac-4913-a742-38b9d1e4abd2",
              "document_type": "document_identification",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh.jpeg"
          },
          {
              "document_key": "75577d34-4ebd-4488-aca8-b064e603c973",
              "document_type": "document_identification_back",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh_back.jpeg"
          },
          {
              "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
              "document_type": "payroll_card_confirmation_video",
              "document_certifier": "electronic_client_side",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/video.mp4"
          }
        ],
      },
      {
        "request_control_key": "d3bc353e-d612-4029-9d77-4dca9171c3b5",
        "payroll_card_reservation_key": "5fb9d810-be74-4d26-959d-c75d10834e93",
        "payroll_card_reservation_status": "pending_withdrawal_disbursement",
        "card_holder_document_number": "12345678901",
        "identifier_number": "1234567890",
        "total_limit_amount": 8000.00,
        "reservation_amount": 250.00,
        "reservation_contract_number": "PCR0123456789",
        "wallet_key": "298e4d37-0f20-4aed-ad66-016f8487afba",
        "payroll_card_type": "social_security_payroll_card",
        "card_holder": {
          "email": "joao.teste@example.com",
          "phone": {
            "number": "352141677",
            "area_code": "11",
            "country_code": "055"
          },
          "address": {
            "city": "Belo Horizonte",
            "state": "MG",
            "number": "7889",
            "street": "Rua Santos",
            "complement": "Apto 243",
            "postal_code": "30112000",
            "neighborhood": "Centro"
          }
        },
        "attached_documents": [
          {
              "document_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
              "document_type": "withdrawal_operation_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
              "document_type": "payroll_card_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "87c23417-c342-4cc7-81b6-81185b6012ce",
              "document_type": "payroll_card_consent_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b1c3e915-6707-49f5-85a9-398ef997fdad",
              "document_type": "selfie",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/selfie.jpeg"
          },
          {
              "document_key": "5769a335-a2ac-4913-a742-38b9d1e4abd2",
              "document_type": "document_identification",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh.jpeg"
          },
          {
              "document_key": "75577d34-4ebd-4488-aca8-b064e603c973",
              "document_type": "document_identification_back",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh_back.jpeg"
          },
          {
              "document_key": "b574b555-e3c9-402a-a869-c4bc27751be8",
              "document_type": "payroll_card_confirmation_video",
              "document_certifier": "electronic_client_side",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/video.mp4"
          }
        ],
      }
   ]
}

3. 状态机

Payroll Card Reservation

Payroll Card Reservation 实体具有以下状态和转换：

状态说明

状态	描述
`pending_document_generation`	等待生成待签署文件
`pending_onboarding`	等待入驻和 KYC 流程
`pending_collateral_reservation`	等待担保品预留
`pending_additional_documents_submission`	边距已批注。等待提交确认视频
`pending_additional_documents_validation`	等待验证确认视频
`pending_withdrawal_disbursement`	等待提款操作放款
`pending_card_issuance`	等待创建钱包和发行卡
`card_issued`	卡已创建并激活
`canceled`	操作已取消

Withdrawal

Withdrawal 实体具有以下状态和转换：

状态说明

状态	描述
`pending_signature`	等待条款签署
`pending_disbursement`	等待提款操作放款
`opened`	已放款，操作激活
`canceled`	操作已取消

Benefit

Benefit 实体具有以下状态和转换：

状态说明

状态	描述
`created`	保险处理中
`pending_emission`	等待保险发行
`active`	保险已发行并激活
`canceled`	保险已取消
`inactive`	保险已过期或失效

4. 取消预留

允许取消薪资卡预留。

限制条件

通过 API 取消仅允许在提款放款之前（状态：pending_withdrawal_disbursement 或更早状态）。如果提款已完成或卡已发行，取消必须通过支持处理，因为涉及财务退款。

PATCH

/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/cancel

Response

STATUS

200 (OK)

请求已成功处理。无返回内容（Body 为空）。

// Empty response body

1. 查询薪资卡预留​

Query Params​

Response​

Payload withdrawal​

Payload withdrawal_data​

Payload prefixed_interest_rate​

Payload disbursement_options​

Payload installments​

Payload payroll_card​

Payload attached_documents​

Payload signature_data​

Payload benefit​

2. 按 CPF 查询薪资卡预留​

Response​

3. 状态机​

Payroll Card Reservation​

状态说明​

Withdrawal​

状态说明​

Benefit​

状态说明​

4. 取消预留​

Response​

1. 查询薪资卡预留

Query Params

Response

Payload withdrawal

Payload withdrawal_data

Payload prefixed_interest_rate

Payload disbursement_options

Payload installments

Payload payroll_card

Payload attached_documents

Payload signature_data

Payload benefit

2. 按 CPF 查询薪资卡预留

Response

3. 状态机

Payroll Card Reservation

状态说明

Withdrawal

状态说明

Benefit

状态说明

4. 取消预留

Response