SmileID AML 能力接入说明

官方文档：

AML Check: https://docs.usesmileid.com/products/for-individuals-kyc/aml-check
One Time AML: https://docs.usesmileid.com/products/for-individuals-kyc/one-time-aml

1. 功能场景

SmileID 的 AML 能力用于对个人进行反洗钱筛查，检查是否命中以下风险来源：

global watchlists
politically exposed persons lists (PEP)
adverse media publications

适用场景：

供应商 KYC / KYB 补充尽调
用户开户注册前 AML 筛查
高风险交易前的增强尽调
存量客户定期复查

这两个能力都不是制裁名单原始库本身，而是通过 SmileID 提供的 AML 筛查服务对提交的个人身份信息进行命中分析。

2. 接口分类

SmileID 官方当前提供两个相关接口：

产品	Method	Sandbox	Production	说明
AML Check	POST	`https://testapi.smileidentity.com/v1/aml`	`https://api.smileidentity.com/v1/aml`	AML 筛查接口
One Time AML	POST	`https://testapi.smileidentity.com/v1/one-time-aml-screening`	`https://api.smileidentity.com/v1/one-time-aml-screening`	一次性 AML 筛查，官方明确说明后续风险变化不会提供更新

关键差异：

AML Check：官方页面没有写 callback_url，也没有明确写“自动持续监控并回调”。
One Time AML：官方明确说明这是一次性检查，后续风险变化不会通知。

因此，按官方文档能确认的信息来看：

这两个接口都是同步调用、同步返回本次筛查结果。
如果你要知道后续是否新增命中，保守实现方式是重新发起 AML 查询。
不要默认 AML Check 自带自动回调或监控通知，除非 SmileID 官方另有书面说明。

3. 认证方式

这两个接口的认证参数都放在 JSON Body 中，不是在 Header 中。

必填认证字段：

partner_id
signature
timestamp

签名规则沿用 SmileID REST API 签名规则：

text

Base64(HMAC-SHA256(timestamp + partner_id + "sid_request", api_key))

注意：

partner_id 和 api_key 必须来自同一环境。
Sandbox 使用 sandbox 的 Partner ID 和 API Key。
Production 使用 production 的 Partner ID 和 API Key。
timestamp 必须和生成签名时使用的值完全一致。

4. 请求 Body

两个接口的官方请求字段基本一致。

官方示例：

json

{
  "birth_year": "1984",
  "countries": ["US"],
  "full_name": "John Leo Doe",
  "job_id": "job-001",
  "partner_id": "8435",
  "search_existing_user": false,
  "strict_match": true,
  "signature": "sample-signature",
  "timestamp": "2021-08-12T17:57:00.614879",
  "user_id": "user-001"
}

字段说明：

字段	是否必填	说明
`partner_id`	是	SmileID Partner ID
`signature`	是	请求签名
`timestamp`	是	请求时间戳
`user_id`	是	业务用户唯一标识
`job_id`	是	本次 AML 任务唯一标识
`countries`	是	国家码数组，官方示例使用 2 位国家码，如 `["US"]`
`full_name`	是	被筛查人的完整姓名
`birth_year`	否，但官方建议	出生年份，用于减少误命中
`strict_match`	否	是否严格匹配，默认 `true`
`search_existing_user`	否	是否从 SmileID 既有成功 KYC 任务中复用姓名和出生年份

5. 请求字段说明

5.1 `countries`

官方说明：

必填
传入客户的 known nationalities
使用 2 位国家码

如果一个人有多个已知国籍，可以按数组传入多个国家码。

5.2 `full_name`

用于 AML 人名匹配。建议尽量传完整姓名，避免缩写、昵称或只传部分字段造成误判。

5.3 `birth_year`

官方建议提供 birth_year，因为这样可以减少 false matches。

这不是强制字段，但在真实生产场景里建议尽量带上。

5.4 `strict_match`

官方说明：

默认值：true
设为 false 时会使用更宽松的匹配规则

业务上：

true：命中更严格，误命中更少
false：召回更多潜在结果，但可能增加人工审核量

5.5 `search_existing_user`

官方说明：

当该值为 true 时，SmileID 会使用先前成功的 Biometric KYC 或 Document Verification 任务中的 full_name 和 birth_year
即使如此，countries 仍然必须传入

这个字段适合已经在 SmileID 做过实名/KYC 的同一用户场景。

6. 返回结果结构

两个接口的官方返回结构基本一致，都是同步返回本次筛查结果。

官方示例结构：

json

{
  "Actions": {
    "Listed": "Listed"
  },
  "PartnerParams": {
    "job_type": 10,
    "user_id": "user-001",
    "job_id": "job-001"
  },
  "SmileJobID": "0000000411",
  "no_of_persons_found": 1,
  "people": [],
  "ResultCode": "1030",
  "ResultText": "Found on list",
  "signature": "sample-signature",
  "StrictMatch": true,
  "timestamp": "2023-02-17T16:24:16.835Z"
}

主要字段说明：

字段	说明
`ResultCode`	筛查结果码
`ResultText`	筛查结果文本
`Actions.Listed`	是否被列入名单
`PartnerParams.job_id`	你的业务任务号
`PartnerParams.user_id`	你的业务用户号
`PartnerParams.job_type`	SmileID 返回的任务类型
`SmileJobID`	SmileID 内部任务号
`StrictMatch`	本次是否启用了严格匹配
`no_of_persons_found`	命中的候选人数
`people`	命中的人物详情列表
`signature`	SmileID 返回签名
`timestamp`	SmileID 返回时间戳

7. 结果码

两个接口官方列出的结果码一致：

Code	Message	Description
`1030`	Listed	Person found on list
`1031`	Not found on list	Person not found on list
`1017`	Not found on list - warning	Person found on media only
`1023`	No match found	There were no matches; Smile suggests checking `strict_match` and `birth_year`
`1015`	Database unavailable	AML database unavailable

业务解释建议：

1030：命中名单/风险记录，应进入人工审核或增强尽调
1031：未命中名单
1017：只命中媒体信息，建议人工复核
1023：没有找到匹配，不等同于绝对安全通过
1015：外部数据源不可用，应重试或走降级流程

8. `people` 字段明细

当命中结果时，people 数组里可能包含以下信息：

字段	说明
`name`	命中的姓名
`addresses`	地址信息
`aliases`	别名
`dates_of_birth`	出生日期
`nationalities`	国籍
`sanctions`	制裁信息
`enforcement_action`	执法/处罚信息
`pep`	PEP 信息
`associations`	关联关系
`news_summary`	新闻摘要
`news`	新闻列表
`adverse_media`	官方标注 deprecated，可能为空

8.1 `sanctions`

官方示例字段：

json

{
  "date_of_birth": "",
  "nationality": "American",
  "source_details": {
    "listed_date": "2020-01-05",
    "source_link": ["https://sanctionslist.com"],
    "source_name": "Office of Foreign Assets Control (OFAC)",
    "source_type": "Sanctions"
  }
}

重点关注：

source_name
source_type
listed_date
source_link

8.2 `pep`

官方示例字段：

json

{
  "pep_level": "1",
  "political_positions": [
    {
      "country": "United States",
      "from": "2020-01-05",
      "position": "Representative",
      "to": "2022-01-05"
    }
  ],
  "sources": [
    {
      "source_link": "https://www.senate.gov/senators/",
      "source_name": "senate.gov"
    }
  ]
}

官方说明：

1 = high
2 = medium
3 = low / Former PEP

8.3 `news_summary`

官方示例字段：

json

{
  "headline": "John Doe involved in investigation",
  "link": "https://news-site.example/article",
  "source": "Example News"
}

如果返回 1017 Not found on list - warning，通常表示命中的主要是媒体信息。

9. 如何接入

推荐接入流程：

text

业务系统生成 user_id/job_id
  -> 后台收集 full_name、countries、birth_year
  -> 生成 timestamp
  -> 生成 signature
  -> POST /v1/aml 或 /v1/one-time-aml-screening
  -> 同步解析 ResultCode / ResultText / people
  -> 根据命中结果落库并进入风控流程

Java / Spring Boot 伪代码：

java

String timestamp = Instant.now().toString();
String signature = signatureService.generateSignature(timestamp, partnerId, apiKey);

Map<String, Object> body = Map.of(
    "birth_year", "1984",
    "countries", List.of("US"),
    "full_name", "John Leo Doe",
    "job_id", jobId,
    "partner_id", partnerId,
    "search_existing_user", false,
    "strict_match", true,
    "signature", signature,
    "timestamp", timestamp,
    "user_id", userId
);

AmlResponse response = restClient.post()
    .uri("/v1/aml")
    .contentType(MediaType.APPLICATION_JSON)
    .body(body)
    .retrieve()
    .body(AmlResponse.class);

如果你要调用 One Time AML，只需要把 URI 改成：

text

/v1/one-time-aml-screening

10. 接入注意点

endpoint 必须严格区分：
- AML Check: /v1/aml
- One Time AML: /v1/one-time-aml-screening
认证参数在 Body 中，不在 Header 中。
job_id 必须唯一，避免本地任务和 SmileID 结果混淆。
countries 是数组，不是单个字符串。
birth_year 虽然不是强制字段，但生产建议传。
strict_match=false 会放宽匹配范围，可能增加人工审核量。
search_existing_user=true 仅在该用户已有成功 SmileID KYC 记录时更有意义。
官方文档没有给 AML Check 写 callback_url，也没有明确持续监控回调机制；不要默认有自动回调。
如果业务需要持续复查，建议自行定期重新调用 AML 接口。
1017 和 1030 都不建议直接自动拒绝，通常应进入人工复核。
1015 应视为外部数据源失败，不应直接判定用户风险。

11. 如何选型

推荐选择方式：

如果你只是做一次性 AML 尽调，选 One Time AML
如果你当前产品文档或商务协议里没有额外说明 AML 持续监控机制，也应按“一次一查”来设计
如果 SmileID 商务侧明确提供了额外 AML 监控/通知能力，应单独确认：
- 是否需要额外开通
- 是否存在 callback
- 结果推送格式是什么
- 监控周期和计费方式是什么

基于当前官方页面本身，能确认的是：

One Time AML 明确是一次性检查
AML Check 页面没有明确写自动回调和持续通知机制

SmileID AML 能力接入说明 ​

1. 功能场景 ​

2. 接口分类 ​

3. 认证方式 ​

4. 请求 Body ​

5. 请求字段说明 ​

5.1 countries ​

5.2 full_name ​

5.3 birth_year ​

5.4 strict_match ​

5.5 search_existing_user ​

6. 返回结果结构 ​

7. 结果码 ​

8. people 字段明细 ​

8.1 sanctions ​

8.2 pep ​

8.3 news_summary ​

9. 如何接入 ​

10. 接入注意点 ​

11. 如何选型 ​

SmileID AML 能力接入说明

1. 功能场景

2. 接口分类

3. 认证方式

4. 请求 Body

5. 请求字段说明

5.1 `countries`

5.2 `full_name`

5.3 `birth_year`

5.4 `strict_match`

5.5 `search_existing_user`

6. 返回结果结构

7. 结果码

8. `people` 字段明细

8.1 `sanctions`

8.2 `pep`

8.3 `news_summary`

9. 如何接入

10. 接入注意点

11. 如何选型