本页内容

整合模式

在 Know Your Customer Limited Public API v2（透过 147 个司法管辖区的即时官方登记处核实公司）之上进行开发，方式不止一种。合适的做法取决于您的需要：完整的企业客户尽职调查流程、已知公司的登记处数据、排定的重新审查、客户尽职调查后的持续监察，或以上各项的组合。本页说明主要的实作方式，并附有序列图，方便您对应到自己的系统。

以上五种方式都使用指南中相同的基础构件：OAuth2 客户端凭证验证、作为工作单位的案件（case）、可透过轮询或（建议）webhooks 追踪的非同步建置过程，以及最后产生的报告。如果您尚未阅读核心概念，建议您先从那里开始。如需每个模式背后确切端点的详情，请参阅 API Reference；如需其回传内容的栏位层级详情，请参阅 Data Dictionary。如要以真实数据试用以上任何一种方式，请申请免费沙盒存取权限，并查看可执行的sandbox test cases。

关于沙盒的诚实说明

以上图表描述的是与正式环境一致的沙盒合约规格。身分核实由第三方（Au10tix）执行，其结果以非同步方式送达；各司法管辖区的延迟时间仅为约数；沙盒输出结果仅供评估用途，不可用于实际合规用途。详见非同步轮询与延迟及沙盒页面。

模式 A：完整企业客户尽职调查流程

这是旗舰模式：从头到尾为新的企业客户进行尽职调查。您搜寻公司、确认申请人、解析股权架构及组织架构图、对董事及最终受益人执行 KYC、审查反洗钱结果、记录决定，并产生报告。样本尽职调查应用程式及端对端核实公司教学均采用此模式实作。

适用情境：当您正在为企业客户进行客户尽职调查，并需要全盘了解：公司身分、谁拥有及控制该公司、是否有人受制裁或为政治敏感人物（PEP），以及一份可供稽核的决定纪录。

端点：/connect/token、POST /v2/Companies/search、POST /v2/Companies、GET /v2/Companies/{id}、GET .../members、GET .../org-chart、GET /v2/Individuals/{id}、GET .../amlchecks、PATCH .../status、GET .../report。

整个流程大致如下：

  1. 公司搜寻：使用 rawname 及 codeiso31662，在该公司所属的登记处中找出该实体。
  2. 申请人确认：选取正确的配对结果并建立案件。
  3. 最终受益人及组织架构图：案件就绪后，读取成员及递回式股权架构树。
  4. 董事及最终受益人 KYC：针对每位需要核实的个人，处理其个人案件并收集文件（详见最终受益人 KYC 及身分核实子流程）。
  5. 反洗钱审查：读取案件的反洗钱结果，审查并排除误判结果。
  6. 决定：于案件状态中记录结果。
  7. 报告：取得可供稽核的 PDF。
KYB 客户尽职调查流程 由您的应用程式到 KYB API 的流程：请求权杖、搜寻或建立公司案件、轮询至架构就绪、读取成员及组织架构图、核实个人、审查反洗钱结果、记录决定，并下载报告。 您的应用程式 KYB API POST /connect/token（client_credentials，scope=PublicApi） access_token（约 10 分钟 TTL） POST /v2/Companies/search + POST /v2/Companies（rawname、codeiso31662） caseCommonId，statusId 0 回圈：轮询至就绪 建议做法：改为订阅 CaseReady webhook GET /v2/Companies/{id} statusId 50/51/57，之后变为 3；架构已填入 = 就绪 GET …/members 及 GET …/org-chart controllingEntitiesAndIndividuals，巢状股东 GET /v2/Individuals/{id}（核实董事及最终受益人） 个人案件、文件、身分核实结果 GET …/amlchecks（审查、排除误判结果） PATCH …/status（记录决定：批准／拒绝） GET …/report?language=en 可供稽核的 PDF（沙盒中仅供评估）
KYB 客户尽职调查：取得权杖、搜寻或建立，接著得知案件已就绪（轮询，或建议订阅 CaseReady webhook），读取成员及组织架构图，核实个人，审查反洗钱结果，作出决定，并下载报告。「就绪」是指架构已填入，而非状态文字本身。
建议使用 webhooks 而非轮询回圈

上述轮询回圈是最容易撰写的做法，但在规模化的情况下，较佳的模式是为 CaseReady 事件注册一个 webhook：一旦案件架构就绪，API 便会立即通知您，让您完全省去轮询步骤。对于短期执行的脚本，轮询仍是不错的备用方案。详见 Webhooks。

最终受益人 KYC 及身分核实（IDV）

在尽职调查流程中，您核实的每位董事或最终受益人都是一个个人案件。您需要处理该个人、读取其文件、上载您所收集的文件，并读回预先验证结果，以及（对身分文件而言）身分核实结果。文件分为两类：预设已取得（已为您取得）及可按需索取（由您请求或上载）。预先验证为同步进行，会检查文件本身（正常、伪造或已过期）。身分核实则是独立的步骤：当您上载 photoid 后，政府相片身分证明步骤会由第三方（Au10tix）以非同步方式核实，并在大约 15 至 30 秒后转为 PASSED 或 FAILED。详见文件及最终受益权及个人。

最终受益人 KYC 及身分核实流程 从公司案件开始：列出成员、开启个人案件、按类别读取文件、上载身分文件、接收同步的预先验证结果，然后接收由第三方提供的非同步身分核实结果，该结果会将政府相片身分证明步骤转为通过或未通过。 您的应用程式 KYB API IDV（Au10tix） GET /v2/Companies/{id}/members 个人成员 caseCommonId GET /v2/Individuals/{id} + 文件 预设已取得／可按需索取 POST …/documents/upload（photoid，multipart） 预先验证（同步）：正常／伪造／已过期 转送 photoid 以进行政府相片身分证明步骤 非同步：结果约于 15 至 30 秒后返回 PASSED 或 FAILED 回圈：轮询个人步骤 GET /v2/Individuals/{id}（读取步骤状态） 政府相片身分证明转为 PASSED／FAILED 最终的个人状态会反映预先验证结果及身分核实结果。
最终受益人 KYC 及身分核实：预先验证为同步进行（正常、伪造或已过期）；身分核实透过第三方（Au10tix）进行，政府相片身分证明步骤会以非同步方式转为 PASSED 或 FAILED，一般需时 15 至 30 秒。请轮询该个人以取得结果。

模式 B：纯登记处数据增值

有时您已经知道自己要处理的是哪一间公司，只需要权威的登记处数据：名称、注册编号、状态、地址、高级职员，以及相关的登记处文件。您不需要申请人流程、个人 KYC 或决定工作流程。这是最轻量的模式。

适用情境：当您想以即时登记处数据及文件丰富或更新公司纪录，而毋须为个人进行客户尽职调查时。例如在您自己的系统中填入公司概况资料。

端点：/connect/token、POST /v2/Companies/search、POST /v2/Companies、GET /v2/Companies/{id}、GET .../documents。

  1. 使用 rawname 及 codeiso31662 搜寻公司（或于 externalCode 中提供注册编号以取得完全相符的结果）。
  2. 建立案件。
  3. 轮询至架构已填入，然后读取实体数据。
  4. 撷取您所需的登记处文件，然后即可停止。您不需要处理个人、反洗钱审查或作出决定。

上述尽职调查流程的前半部分（权杖、搜寻、建立、轮询、读取）正正就是这个模式。您只需在读取实体数据及文件后停止即可。

模式 C：定期审查与更新

现有客户需要按时间表重新核实。您需要针对现时的登记处重新撷取数据，比较自上次以来的变化（状态、高级职员、股权架构），更新审查日期，并为存档制作最新的报告。

适用情境：当您的政策设有审查周期（例如高风险客户需更频繁地审查），而您想要的是特定时点的更新，而非持续监察。

端点：POST /v2/Companies（新案件）或重新读取现有案件、GET .../members、GET .../org-chart、GET .../amlchecks、审查日期更新、GET .../report。

  1. 在审查时为客户重新撷取登记处数据（新案件会反映现时的登记处状态）。
  2. 将新的架构及状态与您储存的纪录比较，并标记重大变化：新任董事、股权架构变动、状态变更。
  3. 如有需要，重新计算反洗钱结果，并清除任何新的命中结果。
  4. 更新审查日期，以排定下一个周期。
  5. 制作新的报告作为该时点的纪录。

详见审查日期及审查、排除、重新计算。如需在两次审查之间持续重新筛查，请使用模式 D。

模式 D：持续监察

客户完成尽职调查后，您会持续监察。您在案件上启用即时监察，处理新出现的制裁、政治敏感人物（PEP）或负面媒体配对警示，以已记录的决定处理每项警示，并保持稽核纪录完整。这在实务上就是持续性 KYB。您可以按时间表轮询警示，或为 AmlMatch 事件注册一个 webhook，让新配对一发生便直接推送至您的系统，而毋须等到下一次轮询。

适用情境：当您需要在两次审查之间持续获得保证，让新受制裁或新出现于负面媒体的客户立即触发警示，而毋须等待下一次排定的审查。

端点：建立案件或已完成尽职调查的案件、启用监察、列出警示、警示详情、处理警示、稽核纪录。

持续监察流程 从已完成尽职调查的案件开始：启用监察，接著在回圈中出现警示，您撷取其详情，以已记录的决定处理它，然后更新案件状态及稽核纪录。 您的应用程式 KYB API 案件已完成尽职调查，接著启用即时监察 案件上的监察已启用 回圈：监察启用期间 出现警示（新的制裁／PEP／负面媒体配对） GET 警示详情（配对对象、原因） 处理警示（确认或撤销，并附上原因） 警示已关闭，决定已记录 重新计算／更新状态；读取稽核纪录
持续监察：在已完成尽职调查的案件上启用监察，然后在警示出现时处理并采取行动。每项已处理的警示都会记录一个决定，并保持稽核纪录完整。

详见即时监察警示及持续性 KYB。

模式 E：嵌入式与后端专用

以上四种模式描述的是 API 呼叫本身。这一种模式讨论的则是这些呼叫存在于何处，以及您的使用者看到什么。您有四个选项，并且可以混合使用。

选项说明适用情境
纯 API（后端）您在伺服器端呼叫 API，并在自己的产品中呈现结果，不使用 Know Your Customer 的介面。您希望完全掌控使用体验，或您只是在进行数据增值而没有终端使用者流程（模式 B）。
样本尽职调查应用程式可复制的参考尽职调查网页应用程式，执行完整的 KYB 流程，并在除错检视画面中显示原始 API 呼叫。您想要一个可运作的参考实作，方便阅读、即日执行并加以调整（模式 A）。
Workspace 控制台位于 workspace.knowyourcustomer.dev 的随时可用操作员控制台：于您的租户之上显示案件清单及分页式案件详情。您的合规审查人员需要浏览并处理案件，而毋须由您自行建置审查介面。
客制化介面您自己的前端，透过您的后端呼叫 API，并按您的工作流程及品牌度身订做。客户尽职调查是您产品的核心部分，而您希望完全嵌入。

常见的做法是：由您的伺服器呼叫 API 支援的客制化客户端尽职调查流程（嵌入式），并由您的合规团队使用 Workspace 控制台进行审查，以样本应用程式作为起始的参考。

没有额外前端或后端开发能量的客户，通常会由 Know Your Customer Limited 本身的交付团队以固定价格，在本页所述的相同 API 之上为他们建置这一层。

非同步轮询与延迟

每一种会建立案件的模式都是非同步的。您建立案件后，需要轮询至案件就绪为止。案件生命周期中有两项规则对所有模式都很重要：

  • 「就绪」是指架构已填入（成员已出现或组织架构图节点已出现），而不是某个状态文字值，也不是任何单一的中间 statusId。案件建置期间，状态文字可能仍然显示「Open」。
  • 中间状态的集合因案件及司法管辖区而异。请以最终状态作为逻辑依据，而非依赖看到某个特定的中间代码。
非同步轮询与状态流程 状态流程：以 statusId 0（Open）建立案件，在其经历 50、51 及 57 的处理过程中进行轮询，接著在架构填入后达到就绪状态，或透过重试或升级处理失败及过期的最终状态。 建立案件 statusId 0（Open） 处理中 statusId 50／51／57 就绪 statusId 3 + 架构 或透过 CaseReady webhook 推送给您 读取结果 以退避方式轮询 失败 重试／升级 已过期 重新建立案件 各司法管辖区的约略延迟时间（沙盒反映正式环境的时间）： GB、SG：数分钟 HK：约 5 至 10 分钟 CN：约 30 至 40 分钟（未经验证） 以上时间范围仅为约数。请以退避方式轮询，并设定充裕的逾时时间；请勿使用紧密回圈。
非同步轮询：以 statusId 0（Open）建立，以退避方式轮询处理中的各个状态，架构填入后达到就绪状态，并透过重试或重新建立处理失败或过期的最终状态。延迟时间因司法管辖区而异，图中所示的范围仅为约数。

如需完整的状态表及错误模型，请参阅参考附录及轮询至就绪。

如果您不想轮询，可以为 CaseReady 事件注册一个 webhook，一旦案件建置完成，API 便会立即推送讯息。轮询适合短期执行的脚本；webhooks 则适合大规模运作，或以事件驱动工作流程。详见 Webhooks。

选择合适的模式

您需要模式
从头到尾为新的企业客户进行尽职调查，包括最终受益人、KYC、反洗钱、决定及报告A：完整企业客户尽职调查
撷取已知公司的权威登记处数据及文件B：登记处数据增值
按时间表重新核实现有客户并记录变化C：定期审查
持续监察已完成尽职调查的客户并处理警示D：持续监察
决定呼叫存在于何处，以及您的使用者看到什么E：嵌入式与后端专用

大部分整合都会结合多种模式：以模式 A 进行尽职调查、以模式 D 持续监察客户，并以模式 C 重新审查。如要试用其中任何一种模式，请申请免费沙盒存取权限、阅读指南、执行sandbox test cases，并在Workspace 控制台中浏览您的案件。