update

2026-08-26 08:47

重要说明：

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

概览

API URL：POST /api/v1/zoloz/applicant/update
API 描述：该接口用于更新当前商户下指定申请人的邮箱或手机号码。

说明：

该接口采用非 null PATCH 语义，仅更新请求中值不为 null 的字段；未传或值为 null 的字段保持不变。
email 和 phone 至少需要提供一个非 null 值。如果两个字段均未提供或均为 null，接口将返回 INVALID_ARGUMENT。
该接口支持使用相同参数重复调用。重复调用后申请人信息保持为请求中指定的值，即符合幂等性。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ不校验该值的唯一性，商户侧需自行保证该业务ID的唯一性。	2026060200001
applicantId	String	50	是	-	待更新的ZOLOZ申请人ID。该申请人必须属于当前商户。	APHK_a1b2c3d4e5f6
email	String	255	否	null	新的用户邮箱，传入时须符合标准的邮箱格式。未传或传入无效值时保持原值不变。	newuser@example.com
phone	String	50	否	null	新的用户手机号码。未传或传入无效值时保持原值不变。	+85298765432

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

API请求结果，包含结果状态、结果码和结果消息。

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

否

本次调用返回的交易ID，可用于业务追踪和问题排查。

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

请求参数非法，例如入参格式错误或缺失必传参数。
请求未能成功到达服务器，例如网络问题或网关故障。
系统限流导致请求被拒绝。

G000000005FID2020030400000000000157****

返回规则

处理结果	返回内容
更新成功	返回 `result` 和 `transactionId`，其中 `result.resultCode=SUCCESS`。
申请人不存在	返回 `result` 和 `transactionId`，其中 `result.resultCode=APPLICANT_NOT_FOUND`。
更新失败	返回 `result` 和 `transactionId`，通过 `resultCode` 和 `resultMessage` 描述失败原因。

字段更新规则

请求方式	`email` 处理结果	`phone` 处理结果
同时传入非 `null` 的 `email` 和 `phone`	更新为新值	更新为新值
仅传入非 `null` 的 `email`	更新为新值	保持不变
仅传入非 `null` 的 `phone`	保持不变	更新为新值
字段未传入或值为 `null`	保持不变	保持不变
`email` 和 `phone` 均未传入或均为 `null`	返回 `INVALID_ARGUMENT`	返回 `INVALID_ARGUMENT`

处理结果

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

当result.resultCode=SUCCESS时，表示申请人信息更新成功。
当result.resultCode=APPLICANT_NOT_FOUND时，表示applicantId 对应的申请人不存在，或不属于当前商户。
当result.resultStatus=F时，表示更新失败，请根据返回的 resultCode 和 resultMessage 排查请求参数或系统错误。

API通用结果码

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

API特有结果码

Reusable RealID update API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	申请人信息更新成功。
APPLICANT_NOT_FOUND	F	`applicantId` 对应的申请人不存在，或不属于当前商户。
INVALID_ARGUMENT	F	输入参数无效。可能原因包括：缺少必填参数、字段超长、邮箱格式无效、`email` 和 `phone` 均未提供非 `null` 值。具体错误信息请查看返回的`resultMessage`。
SYSTEM_ERROR	F	系统内部错误。有关错误详情，请查看返回的`resultMessage`。

代码示例

请求示例

同时更新邮箱和手机号码：

copy
{
    "bizId": "2026060200001", 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "email": "newuser@example.com", 
    "phone": "+85298765432"
}

仅更新手机号码：

以下请求仅更新 phone。由于未传入 email，申请人的邮箱保持不变。

copy
{
    "bizId": "2026060200002", 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "phone": "+85291234567"
}

返回示例

成功返回示例：

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "G000000005FID20200304000000000001570702"
}

失败返回示例：

copy
{
    "result": {
        "resultStatus": "F", 
        "resultCode": "INVALID_ARGUMENT", 
        "resultMessage": "At least one of email or phone must be provided."
    }, 
    "transactionId": "G000000005FID20200304000000000001570703"
}