RFI 集成指南

RFI（Request For Information，补充材料请求）是指用户 KYC 审核过程中，合规团队要求用户补充材料——如地址证明、资金来源等——的流程。RFI 未完成前，用户无法继续交易。

本页是 RFI 全流程的总览：各状态的含义、追踪状态的两种方式，以及平台应如何响应。载荷字段、重试与幂等规则的完整说明见 RFI 状态页面。

追踪 RFI 状态的两种方式

平台可通过两种方式追踪用户的 RFI 状态，两者可同时使用：

RFI 状态

触发时机：

• requested —— 合规审核发现用户资料不完整，或您调用重发接口时触发。
• in_review —— 用户按 RFI 要求提交材料后触发。
• declined —— 用户提交的某项材料未通过审核、需要重新提交时触发。
• accepted —— RFI 全部事项审核通过时触发。
• closed —— 合规团队主动关闭该 RFI、不再要求用户补充材料时触发。

税号（TIN）RFI

RFI 除材料外，还可能向用户索取税号（Tax Number）。这是向账户区域为 EU 的个人用户收集的税号，可能单独出现，也可能与其他事项同时出现。

• 在 /rfi Webhook 的 additional_item 列表中，该事项显示为 Tax Number。
• 用户在 RFI 页面上以自由文本填写——单行的 6–20 位税号，保留前导零。
• 提交税号即完成该事项。同一 RFI 中的其他事项仍保持未完成状态，需要各自作答——一个 RFI 可以同时索取税号与材料。
• 通过 RFI 页面提交税号，与通过 API 或 SDK 提交等效：三者写入同一份数据，因此在任何入口都会显示为已收集。

Webhook：/rfi-status

当用户的 RFI 状态发生变化时，Legend 会向您提供的回调地址发起 POST 请求。

• 该 Webhook 可选开通、默认关闭；需联系 Legend 开通（rfi_status_webhook 选项）。
• 回调路径可自定义，默认为 /rfi-status。
• 开通它不会影响 Legend 向用户发送的 RFI 邮件。

通知内容包含 uid、rfi_unique_id、rfi_status、rfi_url、created_at、updated_at。其中 rfi_url 是 RFI 表单页的完整地址，可直接提供给用户。

完整的载荷字段与要求见 RFI 状态；接口详情见 /rfi-status。

接口要求速览

• 成功判定 —— 仅 HTTP 200 视为成功，响应内容不参与判定，建议返回 {"code":0,"message":"ok"}。
• 响应时间 —— 请在 3 秒内返回，业务逻辑建议异步处理。
• 重试 —— 通知失败（网络异常或非 200 响应）时，Legend 最多重试 3 次、间隔 60 秒。仍失败会记录错误日志；如需补推历史事件，请联系 Legend 技术支持。
• 幂等 —— 同一 RFI 可能因状态变更或重试收到重复通知；请按 rfi_unique_id + rfi_status 做幂等处理。
• 顺序 —— 通知可能乱序到达，请按 updated_at 判断最新状态，避免旧状态覆盖新状态。
• 鉴权 —— 请求头会携带 api-key 等鉴权信息，请务必校验后再处理。详见 Webhook 请求签名验证。

轮询：GET /app/kyc-status

如未开通 Webhook，或某次通知失败，可调用 GET /app/kyc-status（Bearer Token 鉴权）并读取 events.RFI：

"RFI": {
  "created_timestamp": "2024-09-13T04:06:35.000000Z",
  "updated_timestamp": "2024-09-13T04:06:35.000000Z",
  "grace_period_end_timestamp": "2025-03-10T04:06:35.000000Z",
  "status": "Requested",
  "message": "...",
  "url": "https://www.legendtrading.com/rfi/r/xxxxxx"
}

用户处于 RFI 或 EDD 状态时

当用户处于 RFI 或 EDD 状态时，以下接口会返回 RFI_REQUIRED（或 EDD_REQUIRED）错误：

• /app/offramp/generatewallet
• /app/withdraw
• /app/depositaccount
• /app/orderByFiat
• /app/offrampsell
• /depositaccount/local

RFI Required 响应：

{
    "message": "To complete the verification process for your account, please check your email. We have sent instructions on how to finalize the verification of your latest deposits/withdrawals.",
    "errors": {
        "rfi": "RFI required"
    },
    "error_code": "RFI_REQUIRED",
    "data": {
        "url": "{RFI url}"
    }
}

收到该响应时，请引导用户前往 data.url 完成所需信息的补充。完整错误码清单见错误码与调试示例页面。

相关文档

• RFI 状态 —— 触发时机、通知内容与接口要求
• /rfi-status —— RFI 状态同步 Webhook
• GET /app/kyc-status —— 轮询接口，events.RFI / events.EDD
• Webhook 请求签名验证