sharetoken create

2026-09-24 03:06

重要说明：

所有请求及返回参数均严格以官网API文档为准。
API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用，不保证稳定性及兼容性，请勿在生产环境中依赖这些字段，ZOLOZ保留随时修改或删除这些字段的权利，且无需另行通知。

概览

API URL：POST /api/v1/zoloz/sharetoken/create
API 描述：Donor（数据提供方）为指定 Recipient（数据接收方）生成一次性 ShareToken，授权该 Recipient 在 Reusable RealID 流程中复用指定申请人的 KYC 数据。

说明：

调用前需确保已满足以下条件：

Donor 已开通 ShareToken 创建能力。
Donor 与 Recipient 之间已建立有效的数据共享合作关系。
指定申请人已挂载可共享的证件和人脸数据。

ShareToken 的有效时间为 20 分钟且只能使用一次，仅允许创建时指定的 Recipient 使用。
ShareToken 为不透明字符串，请勿解析或修改。Donor 应通过安全的服务端链路将 ShareToken 传递给 Recipient。
对于相同 Donor、bizId、applicantId 和 recipientClientId 的重复请求，如果原 ShareToken 仍在有效期内且未被使用，接口将返回同一个 ShareToken，即符合幂等性。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ不校验该值的唯一性，商户侧需自行保证该业务ID的唯一性。	2026053000014
applicantId	String	50	是	-	Donor 侧申请人 ID。该申请人必须属于当前 Donor，且已挂载可共享的 KYC 数据。	APHK_a1b2c3d4e5f6
recipientClientId	String	32	是	-	Recipient 接入 ZOLOZ API 时使用的 `clientId`。生成的 ShareToken 仅允许该 Recipient 使用。	2188499706886568
sceneCode	String	64	否	null	客户业务场景标识，可用于区分业务场景和问题排查。	KYC_REUSE

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
shareToken	String	否	一次性共享凭证。仅当 `result.resultStatus=S` 时返回。该字段为不透明字符串，请勿解析或修改。	st_550e8400-e29b-41d4-a716-446655440000
expireTime	Long	否	ShareToken 的过期时间，采用 13 位毫秒级时间戳。仅当 `result.resultStatus=S` 时返回。	1784161200000

ShareToken使用规则

ShareToken 的有效期为创建成功后的 20 分钟，实际过期时间以 expireTime 为准。
ShareToken 只能由创建时 recipientClientId 指定的 Recipient 使用。
ShareToken 在 /api/v1/zoloz/realid/reusable/initialize 初始化成功后将立即被消费，后续无法重复使用。
ShareToken 过期、已被使用或 Recipient 不匹配时，后续数据复用请求将失败。
Donor 应在 expireTime 之前通过安全的服务端链路将 ShareToken 传递给 Recipient。

处理结果

根据请求结果执行下一步的响应动作，具体如下：

当result.resultCode=SUCCESS时，表示ShareToken 创建成功，请使用返回的 shareToken 和 expireTime进行后续数据复用流程。
当result.resultStatus=F时，表示ShareToken 创建失败，请根据返回的 resultCode 和 resultMessage 排查请求参数、申请人数据或合作关系。

API通用结果码

有关通用结果码的完整列表，请参见API通用结果码。

API特有结果码

Reusable RealID sharetoken create API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	ShareToken 创建成功。
APPLICANT_NOT_FOUND	F	`applicantId` 对应的申请人不存在，或不属于当前 Donor。
DONOR_DATA_UNAVAILABLE	F	指定申请人没有可共享的 KYC 数据，例如证件或人脸数据缺失，或相关数据不满足复用要求。
PARTNERSHIP_NOT_ACTIVE	F	Donor 与指定 Recipient 之间不存在有效的数据共享合作关系。
INVALID_ARGUMENT	F	输入参数无效。可能原因包括：缺少必填参数、字段超长或 `bizId`、`applicantId`、`recipientClientId` 包含英文冒号（`:`）。具体错误信息请查看返回的`resultMessage`。
SYSTEM_ERROR	F	系统内部错误。有关错误详情，请查看返回的`resultMessage`。

代码示例

请求示例

copy
{
    "bizId": "2026053000014", 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "recipientClientId": "2188499706886568", 
    "sceneCode": "KYC_REUSE"
}

返回示例

成功返回示例：

copy
{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success"
  },
  "shareToken": "st_550e8400-e29b-41d4-a716-446655440000",
  "expireTime": 1784161200000
}

失败返回示例：

copy
{
  "result": {
    "resultStatus": "F",
    "resultCode": "APPLICANT_NOT_FOUND",
    "resultMessage": "The applicant does not exist or does not belong to the current donor."
  }
}