查询卡片验证码接收设置
GET /openapi/v2/cards/{cardId}/3ds-contact
沿用现有 OpenAPI 签名认证。路径参数 cardId 是卡片查询返回的卡标识,不是完整卡号或数据库主键;仅能操作凭证所属租户的卡片。
支持修改的卡片返回 EMAIL / PHONE 操作;不支持的卡片返回 deliveryMode=UNSUPPORTED、空操作列表。未确认的联系方式为空,不回退用户账号邮箱。存在待处理修改时,查询会读取渠道当前联系方式,与申请值一致后自动确认原记录;无待处理修改时只查本地。
响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
providerName | string | 渠道标识,仅作展示,不用于路由或判断能力。 |
deliveryMode | string | PROVIDER 渠道维护接收地址;UNSUPPORTED 不支持修改。 |
emailMasked | string/null | 平台已确认的脱敏邮箱。 |
phoneMasked | string/null | 平台已确认的脱敏手机。 |
version | integer | 每次确认修改成功递增。 |
supportedActions | string[] | 可用操作 EMAIL、PHONE,不支持时为空。 |
pending | boolean | 是否有尚未终结的修改;为 true 时暂停其他修改。 |
operations | array | 最近 20 条修改记录,结构见下表。 |
修改记录字段
修改接口为响应 data,查询接口为 operations[] 元素。
| 字段 | 类型 | 说明 |
|---|---|---|
operationNo | string | 平台操作编号。 |
requestNo | string | 调用方幂等号。 |
field | string | EMAIL 或 PHONE。 |
targetMasked | string | 脱敏的新联系方式。 |
status | string | UNKNOWN、ACCEPTED、CONFIRMED、FAILED。 |
providerCode | string/null | 渠道安全结果码,可为空。 |
createdAt | string | 创建时间。 |
updatedAt | string | 更新时间。 |
状态与重试
- 外层
code=200表示平台已处理请求,不代表联系方式已生效。 UNKNOWN:可能仍在提交,或结果不确定;ACCEPTED:渠道已受理,尚未确认生效。两者均阻止该卡的其他联系方式修改。CONFIRMED:平台依据外部证据确认已生效;FAILED:明确拒绝,或核实最终未生效。两者允许后续新修改。- 同一
requestNo、相同内容返回原操作;改变内容返回UCARD_REQUEST_CONFLICT。未知结果不得换号绕过,先查询以触发自动核实;持续无法确认时再联系平台,OpenAPI 不提供人工终结接口。 - 不支持修改返回
UCARD_CONTACT_UNSUPPORTED;已有待核实操作返回UCARD_CONTACT_PENDING;参数无效返回UCARD_CONTACT_INVALID。这些标识出现在msg中,不替代外层数字code。
自动核实
ACCEPTED 可立即核实;UNKNOWN 创建满 120 秒后才核实,以保护仍可能在发送的修改请求。匹配成功后,本次查询返回新的脱敏联系方式、递增的 version 和原操作的 CONFIRMED 状态;无其他待处理修改时 pending=false。
渠道字段缺失、脱敏、值不一致、查询失败或超时时,保留原确认值和待处理状态,可稍后再次查询。超时本身不代表修改失败。每次符合条件的查询至多发起一次只读请求,最长等待 10 秒,不会重发联系方式修改。确认设置生效不代表真实验证码已送达。
