本頁內容

整合模式

在 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 控制台中瀏覽您的案件。