Z Zise Developers
/
卡发行 › API 参考 › 开卡申请

补件 —— 换一张托管屏链接给终端用户

POST /v1/cards/applications/{id}/supplement-sessions scope: cards:write
代会员调用 · 必带 x-on-behalf-of 需 x-idempotency-key

申请单进 need_docs 时（上游要求补充用卡人材料），用这一条拿一个我方托管屏的一次性 URL，转交给终端用户。他在那一页重新拍摄并上传证件照，提交后你的申请单自动继续，无需你再调任何接口。

── 为什么是托管屏，不是一个 JSON 提交口 ──这条线上「交材料」的实质是换掉证件影像 —— 我方递给上游的照片取自该会员此刻的实名档案，不取提交体里的任何字段。一个只收标量的提交口会把这一轮补件消耗掉、把同一份旧照片再推一次：终端用户那侧显示「已提交」，然后被同一个理由驳第二次。而这条路是一次性的 —— 工单过期，申请单转 failed，开卡费退回，卡没开成。

影像与 KYC 同一条边界：永不经你的服务器。你拿到的只有一个 URL。

── 链接的三重绑定 ──绑会员、绑这一张工单、24 小时一次性。提交成功即失效。用户填错重来不消耗它（校验失败可以在同一页重填）。

⚠ 别把这条链接缓存下来复用。 它能以那个会员的名义提交材料。每次要交材料就现调一次，一次调用的成本远低于一条常驻的提权链接。

⚠ 只有 GET /v1/cards/applications/{id} 的 supplement.status 是pending 时才签得出票。已经交过（submitted）时回 404 ——再签一张等于给用户一个点进去只会看到「链接已失效」的入口。

⚠ 待补项里的姓名 / 生日 / 证件号 / 居住地址那几档，这一屏改不了（页面会如实标出来并说明去哪儿办）：改身份数据要重新过我方实名审核，而换一张更清晰的照片不必 —— 后者若也退回重审，这个会员的转账 / 理财 / 汇款会因为实名等级不足而全线停摆，为的却是某一家发卡机构的图像质量意见。

前置条件

  • 该申请单有一张 status = pending 的补件工单

路径参数

字段类型必填说明
id string 必填 申请单 id。带不带 cap_ 前缀都收。
字段类型必填说明
x-idempotency-key string 必填
x-on-behalf-of string 必填 代哪个会员调用。必须是这张单的主人 —— 不是则回 404。

响应

201票据已签发
{
  "id": "kyc_9f2c81a4d7e34b06b1c5a83e7d420f6e",
  "hosted_url": "https://api.zise.com/hosted/card-supplement/kyc_9f2c81a4d7e34b06b1c5a83e7d420f6e",
  "expires_at": 1786000000
}
400idempotency_key_required · idempotency_key_invalid · member_context_required · member_not_found
404not_found —— 申请单不存在、不在这个会员/这个商户名下， 或此刻没有待办的补件工单。四种同一响应，不区分 （区分开就是一个申请单状态探测器）。
请求 
curl -X POST 'https://api.zise.com/v1/cards/applications/{id}/supplement-sessions' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY'
const res = await fetch("https://api.zise.com/v1/cards/applications/{id}/supplement-sessions", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
  },
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/cards/applications/{id}/supplement-sessions",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zise.com/v1/cards/applications/{id}/supplement-sessions",
    nil)
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
res, err := http.DefaultClient.Do(req)
// 金额字段用 string 接，不要 float64
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zise.com/v1/cards/applications/{id}/supplement-sessions"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zise.com/v1/cards/applications/{id}/supplement-sessions');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
  ],
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
201 
{
  "id": "kyc_9f2c81a4d7e34b06b1c5a83e7d420f6e",
  "hosted_url": "https://api.zise.com/hosted/card-supplement/kyc_9f2c81a4d7e34b06b1c5a83e7d420f6e",
  "expires_at": 1786000000
}