/app/kyc-status

接口说明

/app/kyc-status 接口用于主动查询用户在 Legend Gateway 平台上的 KYC（了解你的客户）认证实时状态及相关的合规事件详情（如 EDD、RFI）。

功能与应用场景

此接口主要用于以下场景：

状态轮询：在提交用户 KYC 申请后，您的服务器可以定期调用此接口，以主动获取最新的审核进度与合规要求。
状态同步：当用户登录您的平台时，可调用此接口获取其 KYC、EDD、RFI 的完整状态，从而决定是否展示或限制法币交易功能。
用户引导：根据返回的 events 详情，您可以精准地引导用户完成当前所需的操作（如回复 EDD 邮件或补充 RFI 信息，用户收到标题为“Automated Update: RFI Submission is Approved” 的邮件，表示RFI已经审核通过）。
作为 Webhook 的补充：在未实现或 Webhook 通知异常时，可作为备用手段获取状态。

请求方式

方法: GET
认证: 需使用有效的 Bearer Token 进行认证。

请求参数

参数名	类型	必填	说明
`user_id`	String	是	用户在您平台上的唯一标识符。此 ID 需与调用 KYC 提交 API 时使用的 `uid` 一致。

成功响应详解

接口成功响应将返回一个包含用户 KYC 主状态及所有相关事件详情的 JSON 对象。以下是字段说明及状态处理指引：

{
  "user_id": "aaaaaaa", // 查询的用户标识
  "kyc_status": "approved", // 用户当前的KYC主状态
  "updated_timestamp": "2024-05-08T06:05:31.000000Z", // 状态最后更新时间
  "poa_issued_date": "2024-10-10", //POA issuedDate
  "events": { // 所有相关的合规事件详情
    "EDD": { // 增强尽职调查事件
      "message": "...", // 给用户的提示信息
      "created_timestamp": "...",
      "updated_timestamp": "...",
      "status": "Completed" // EDD状态
    },
    "RFI": { // 信息索取事件
      "created_timestamp": "...",
      "updated_timestamp": "...",
      "grace_period_end_timestamp": "...", // RFI宽限期截止时间
      "status": "Requested", // RFI状态
      "message": "...",
      "url": "https://..." // 用户完成RFI的链接
    },
    "KYC": { // KYC事件详情
      "created_timestamp": "...",
      "updated_timestamp": "...",
      "status": "approved"
    }
  }
}

状态与事件处理指引

类别	关键字段	取值与说明	建议操作
KYC 主状态	`kyc_status`	`null`, `not_started`, `started`, `in_progress`	提示用户填写信息：引导用户前往 KYC 页面完成信息填写与提交。
		`in_review`, `submitted`, `escalated`	告知用户正在审核：告知用户申请已提交，正在审核中。
		`approved`	用户已批准：用户已完成 KYC 验证，可进行交易。
		`rejected`	用户已拒绝：用户无法进行交易，请联系客服。
EDD 事件	`events.EDD`	`empty` (空)	无需操作：用户当前未被要求进行 EDD。
	`events.EDD.status`	`In Progress`	提示用户回复邮件：通知用户查看并回复 Legend 发出的 EDD 邮件。
		`Failed`	EDD 未通过：用户无法进行交易。
		`Completed`	EDD 已完成：用户可以交易。
RFI 事件	`events.RFI`	`empty` (空)	无需操作：用户当前未被要求补充信息。
		`Accepted`	无需操作：用户已接受 RFI 请求。
	`events.RFI.status`	`Requested`	引导用户完成 RFI：通知用户查收邮件，并访问 `events.RFI.url` 链接提供信息。
		`In Review`	告知用户正在审核：告知用户补充信息已收到，正在审核中。
		`Declined`	RFI 未通过：用户无法进行交易。
	`events.RFI.grace_period_end_timestamp`	早于当前时间 (< now)	宽限期外：用户未在宽限期内完成 RFI，无法交易。
		晚于当前时间 (> now)	宽限期内：用户仍在 RFI 宽限期内，可以交易。

替代方案：Webhook 通知（推荐）

除了主动轮询，我们更推荐您实现 kyc-status Webhook 回调接口。

优势：当用户 KYC 或相关事件状态发生变更时，Legend 系统会主动实时推送通知到您的服务器，无需频繁轮询，效率更高。
建议：可将本接口作为兜底或特定查询的补充，与 Webhook 结合使用。

错误处理

401 Unauthorized：Token 无效或缺失。
404 Not Found：提供的 uid 在系统中不存在。
422 Unprocessable Entity：请求参数格式错误，如 uid 为空。

此接口提供了用户合规状态的完整视图，是您集成引导、状态同步和风险控制的核心工具。