文件与签名
本节详细介绍文件生成流程和电子签名流程，包括外部流程和 Qi Sign 流程。
备注
如果客户已接入 QISign 签名流程，本节中的条目均为可选项。
1. 文件 Webhook
创建操作后，文件（payroll_card_term、withdrawal_operation_term 和 payroll_card_consent_term）将异步生成。API 会为每份文件发送一个 Webhook，通知文件状态变更。
注意
如果客户不使用 QISign，客户必须实现对此 Webhook 的处理，以捕获文件 URL 并通过所选的外部认证机构引导 受益人完成签名。
通过 Webhook 跟踪
要查看完整的 payload 结构、事件场景以及如何捕获 URL，请参阅 Webhook 手册中的**文件 Webhook（生成与验证）**章节。
2. 外部文件签名
此接口用于当客户端（客户侧）或外部合作伙伴收集签名和生物特征数据时。客户必须发送已签名的文件和生物特征数据进行验证。
注意
只有当签名流程不是 Qi Sign 时，才应调用此步骤。如果使用 Qi Sign，确认将自动完成。
发送前
使用文件上传接口上传 5 份必要文件（自拍照、身份证正反面、卡片合同和取款合同），以获取 document_key。
请求
POST
/payroll_card_reservation/social_security/{payroll_card_reservation_key}/signatureRequest Body
{
"documents": [
{ "document_type": "selfie", "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab" },
{ "document_type": "document_identification", "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789" },
{ "document_type": "document_identification_back", "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789" },
{ "document_type": "payroll_card_term", "document_key": "9f8e7d6c-5b4a-3210-fedc-ba9876543210" },
{ "document_type": "payroll_card_consent_term", "document_key": "d9b64eae-6e11-4b82-92f0-a0e1a3049eee" },
{ "document_type": "withdrawal_operation_term", "document_key": "a05c74eb-542a-4820-8954-eef92ebb383f" }
],
"ip_address": "192.168.1.100",
"signature_datetime": "2025-01-15T14:30:00Z",
"similarity_score": 0.95,
"biometry_analysis_reference": "serpro"
}
请求体详情
| 字段 | 类型 | 描述 | 必填 |
|---|---|---|---|
| documents | array | 所需的 5 份文件列表 | 是 |
| biometry_analysis_reference | string | 生物特征分析参考 | 是 |
| signature_datetime | string | 签名日期和时间（ISO 8601） | 是 |
| ip_address | string | 签名时的 IP 地址 | 是 |
| similarity_score | float | 生物特征相似度分数 | 是 |
生物特征分析参考枚举值（Biometry Analysis Reference）
| 枚举值 | 描述 |
|---|---|
| serpro | 当 similarity_score 通过 Detran（由 Serpro 提供的服务）的带照片文件数据库查询返回时使用 |
| tse | 当 similarity_score 通过 TSE 的带照片文件数据库查询返回时使用 |
| not_found | 当面部生物特征未在任何政府数据库（serpro 或 tse）中找到时使用。此时 similarity_score 应为 null 或由合作伙伴返回的自拍照与官方带照片文件的相似度。 |
documents 中的条目
| 字段 | 类型 | 描述 | 格式 | 必填 |
|---|---|---|---|---|
| document_type | string | 文件类型 | 枚举值："selfie"、"document_identification"、"document_identification_back"、"payroll_card_term"、"payroll_card_consent_term"、"withdrawal_operation_term" | 是 |
| document_key | string | 文件唯一密钥 | UUID v4 | 是 |
文件类型说明：
selfie：受益人照片document_identification：身份证件正面document_identification_back：身份证件背面payroll_card_term：已签名的卡片条款与条件payroll_card_consent_term：已签名的卡片申请同意书withdrawal_operation_term：已签名的取款操作条款
QI Sign
QI Tech 提供符合 IN 138 规定的签名服务，包括面部生物特征识别和文件提交。
如需报价，请联系我们 的商业团队：
comercial@qitech.com.br 或 (11) 2339-4763
响应
STATUS
200 (OK)Response Body
{
"payroll_card_reservation_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
"payroll_card_reservation_status": "pending_onboarding",
"attached_documents": [
{
"document_key": "0b6c9bb9-0bc1-4fd2-9aab-3ccf5c8bc69d",
"document_type": "withdrawal_operation_term",
"document_certifier": "electronic_client_side",
"document_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term.pdf",
"document_status": "signed",
"document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
"signature_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term_signed.pdf",
},
{
"document_key": "f974bb60-ff4c-4027-9d88-399470586691",
"document_type": "payroll_card_term",
"document_certifier": "electronic_client_side",
"document_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_term.pdf",
"document_status": "signed",
"document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
"signature_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_term_signed.pdf",
},
{
"document_key": "0133eda8-0e82-41d9-ae8d-7020f023b0f9",
"document_type": "payroll_card_consent_term",
"document_certifier": "electronic_client_side",
"document_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_consent_term.pdf",
"document_status": "signed",
"document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
"signature_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_consent_term.pdf",
},
{
"document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab",
"document_type": "selfie",
"document_certifier": "electronic_client_side",
"document_url": "https://storage.googleapis.com/live-doc-api/documents/selfie.pdf",
"document_status": "generated"
},
{
"document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789",
"document_type": "document_identification",
"document_certifier": "electronic_client_side",
"document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification.pdf",
"document_status": "generated"
},
{
"document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789",
"document_type": "document_identification_back",
"document_certifier": "electronic_client_side",
"document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification_back.pdf",
"document_status": "generated"
}
]
}
响应体详情
| 字段 | 类型 | 描述 |
|---|---|---|
| payroll_card_reservation_key | string | 薪资卡预约密钥 |
| payroll_card_reservation_status | string | 预约状态（pending_onboarding） |
| attached_documents | array | 文件及其状态列表 |
信息
确认两份文件的签名后，薪资卡的状态将变更为"pending_onboarding"，表示操作正在等待卡片入网流程。
常见错误
404 - Document Not Found
{
"title": "Document Not Found",
"description": "Document selfie not found",
"translation": "Documento selfie não encontrado"
}
说明： 当请求中提供的 document_key 在系统中未找到时，会发生此错误。请检查是否通过文件上传接口正确获取了 document_key。
3. 签名确认
无论使用何种签名方式（外部或 Qi Sign），成功完成流程后，您将收到一个预约状态变更 Webhook。
请参阅主流程手册中的状态变更 Webhook 章节，查看状态为 pending_onboarding 的 payload 示例。