跳转到主要内容
POST
Python
本指南可帮助您在将数据从其他服务商迁移至 Didit 时选择合适的导入路径。客户通常用“导入”一词指代两种不同的操作:
  • 导入历史验证记录:重建已完成的 KYC、KYB、交易监控或工作流规则记录,使 Didit 能够展示旧服务商的历史。请使用 POST /v3/session/imports/。
  • 导入运营数据:创建用户、企业、资料人脸、黑名单条目或白名单条目,使 Didit 能够在后续检查中使用这些数据。请使用实体、人脸和名单 API。
验证导入会为 KYC 和 KYB 创建历史记录,并设置 session_type: "MIGRATED"。这些导入不会向终端用户发送邮件,不会将用户重定向至托管流程,也不会重新执行原始验证。导入的记录会出现在会话列表、实体档案和交易视图中,并在适用时出现在 GET /v3/session/{session_id}/decision/ 中。

应选择哪种导入方式

如果您只需要用户或企业档案用于后续检查,请不要导入历史验证会话,而应使用用户或企业实体 API。如果您希望旧服务商的决策结果、证件字段、警告或证据在 Didit 中以合规历史的形式呈现,请使用 POST /v3/session/imports/。

各服务商可以迁移哪些内容

只要您导出并转换数据,Didit 就接受标准 CSV 或 NDJSON 文件,因此可以从任何服务商迁移。导入格式始终为 Didit 的标准架构。

迁移流程

  1. 确定您要导入的是历史记录、档案、人脸、名单、交易还是规则。
  2. 自行从旧服务商导出数据。请勿将旧服务商的 API 密钥发送给 Didit。
  3. 将服务商导出的数据转换为对应的 Didit 标准 CSV 或 NDJSON 模板。
  4. 对于大规模迁移,建议使用 NDJSON,并拆分为可独立重试的文件。
  5. 创建导入任务并轮询进度。
  6. 获取行错误,仅修复失败的行并重试。所有导入任务都以其自然外部 ID 实现幂等性。

创建导入任务

使用单个 multipart 请求创建导入任务:
对于较小的、由电子表格驱动的迁移,请使用 CSV;对于大规模迁移,请使用 NDJSON。对于 100k+ 行的数据,NDJSON 更便于流式传输、拆分、校验和重试。 每个应用最多可同时运行 4 个导入任务,因此请将大规模迁移拆分为多个文件,并为每个文件启动一个任务。每个任务会并行下载每行记录的媒体文件。因部署或工作进程重启而中断的任务,会从最后导入的行自动继续,无需您重新启动。 导入交易时,请省略 workflow_id:

请求字段

记录的跟踪与去重

请求字段中没有数据来源参数:所有导入均使用 Didit 的标准架构。每条导入的记录都会存储 metadata.imported_from = "generic",以便追溯。 user_verification 和 business_verification 导入会在应用内按 external_id 对行去重,因此重试同一文件不会产生重复记录。transactions 导入则改为按 transaction_id 去重。 服务商迁移(source=provider)会将每条记录存储为 <provider>:<id>,例如 sumsub:5f8c0e2a9b1d4c3e2f1a0b9c。如果用户验证文件导入时发送的是服务商的纯 ID(5f8c0e2a9b1d4c3e2f1a0b9c),系统会将其识别为同一条记录,两个方向均适用。因此,您可以先通过文件开始迁移,再用服务商迁移完成,反之亦然,不会导入重复记录。

导入证件照片、视频和自拍证据

对于 import_type=user_verification,您可以从之前的服务商导入原始证件照片、证件/活体采集视频以及自拍照。 请使用以下标准列: 对于大批量迁移,请使用 HTTPS URL。Didit 会下载每个文件,验证 URL 是否安全,存储一份 Didit 自有副本,并将其关联到导入的会话。图片会被压缩;视频按原样存储。小批量导入时可以为图片内联 base64,但视频必须始终以 URL 形式提供,因为 base64 会使每个视频体积增加约 33%,很快就会超过单文件导入限制。 以下是使用服务商托管媒体 URL 的 NDJSON 行示例:
重要的媒体规则:
  • URL 必须使用 https。
  • URL 不得解析为私有 IP、localhost、链路本地地址范围或内部元数据主机。
  • 图片可以使用 URL 列,也可以使用对应的 *_base64 备用列;两者都设置时,以 base64 为准。视频仅支持 URL,不存在 *_video_base64 列。
  • 视频必须为 mp4、webm 或 mov 格式,且每个视频最大 10 MB。超过大小限制或非视频文件将作为行错误被拒绝。
  • Didit 强制执行连接/读取超时和最大文件大小限制,并且不会无限重试。
  • 媒体下载失败会记录为行错误,不影响导入的其余部分继续进行。
  • 如果服务商没有提供媒体,请将这些列留空。Didit 仍会导入结构化的决策和证件字段。
  • 导入的图片和视频作为历史审核的证据。Didit 默认不会对导入的历史媒体重新运行 OCR、活体检测或证件欺诈分析。

轮询进度

响应包含 status、import_type、total_rows、processed_rows、created_count、updated_count、skipped_count、failed_count 和 checkpoint_row。

下载行错误

每个错误包含 row_number、external_id、error 和 raw_row,以便您只修复失败的行并重试。

滥用防护

通过 POST /v3/session/imports/ 发起的历史导入任务默认处于禁用状态。Didit 会在审核后按组织启用此功能,因为这些任务可能处理数百万行数据并下载媒体。本指南中的常规运营数据导入(创建用户、创建企业、上传用户档案人脸、上传人脸黑名单,或添加名单条目)除正常的 API 密钥权限、产品可用性和这些端点的速率限制外,无需特别的迁移启用。 历史导入任务还运行在隔离的工作节点上,并设有文件大小限制、行数预算、仅限 HTTPS 的媒体 URL、私有网络 URL 拦截,以及每个应用最多 4 个活跃导入任务的限制,并会记录每行的错误。

标准状态

幂等性

Didit 将 external_id 用作用户验证和企业验证导入的幂等键,按应用范围限定。交易导入使用 transaction_id,同样按应用范围限定。重复导入同一文件时,会跳过已导入的行,并创建尚未处理的行。

导入用户、个人资料人脸和黑名单

如果您不需要重建已完成的验证会话,请使用以下路径:

导入用户资料

使用 POST /v3/users/create/ 创建用户,或通过 导入和导出用户 中的 Business Console CSV 导入功能创建用户。此操作只会创建或更新 VendorUser 资料,不会创建验证会话、KYC 决策、证件报告、警告或 Webhook 历史记录。 当您希望 Didit 在后续检查前就知道某位客户的存在,或需要补充 display_name、标签或元数据等类似 CRM 的字段时,请使用此方式。

上传可信的个人资料人脸

用户存在后,使用 POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ 上传可信的资料人脸。此操作会将生物特征证据关联到用户资料,并为其建立索引,以用于重复检测和人脸搜索。 此操作不会将该人脸加入黑名单。如果您有来自此前 KYC 服务商的可信的个人资料图像,并希望 Didit 在未来的检查中与之比对,可以使用此方式。

导入人脸黑名单和白名单

如需直接拦截或放行某张人脸,请使用 POST /v3/lists/{list_uuid}/entries/face-upload/,并使用人脸类型名单。Didit 会提取生物特征向量并保存为名单条目。 此方式适用于已知欺诈者图像、可信白名单人脸,或服务商欺诈名单的迁移。如果人脸来自已有的 Didit 会话,请优先使用 POST /v3/lists/{list_uuid}/entries/ 并传入 reference_session_id。Didit 会从该会话中提取正确的人脸,并将条目与来源关联。

导入用户、企业、证件、钱包、邮箱、电话、IP 或设备名单

对于非人脸类名单的值,请使用 POST /v3/lists/{list_uuid}/entries/。此路径适用于服务商黑名单、白名单、拒付名单、钱包地址、已知风险 IP、设备指纹、证件号码、邮箱、电话、用户或企业。

后续步骤

导入用户

加载用户资料并关联可信的个人资料人脸。

导入企业

在执行 KYB 之前加载企业资料。

上传资料人脸

为已导入的用户关联可信人脸图像。

向名单上传人脸

将人脸添加到黑名单或白名单。

创建名单条目

将电话、邮箱、钱包、证件、IP、设备、用户或企业导入名单。

速率限制

设计安全的迁移循环与重试机制。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

import_type
enum<string>
默认值:user_verification

要导入的内容:历史用户验证会话、历史企业验证会话、工作流自定义状态规则或历史交易监控记录。

可用选项:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

导入的会话或状态规则应关联的工作流 UUID。对于 user_verification、business_verification 和 status_rules 为必填项。对于 transactions 请省略。

source_format
enum<string>

可选。如果省略,将根据上传文件的扩展名推断。

可用选项:
csv,
ndjson
file
file

规范的 CSV 或 NDJSON 文件。大批量导入请使用 NDJSON。最大上传大小 25 MB(更大的文件请使用 source_file_url)。与 source_file_url 互斥。

source_file_url
string<uri>

文件上传的替代方案。必须是解析为公共地址的 HTTPS URL(私有/回环网络将被拒绝)。与 file 互斥。

source
enum<string>

provider 表示这是从另一家身份证件验证服务商进行的迁移。文件导入时请省略。

可用选项:
file,
provider
provider
enum<string>

迁移来源,来自 GET /v3/session/imports/providers/。当 source 为 provider 时必填。

可用选项:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

服务商的只读密钥,其字段名称由 credential_fields 列出。静态加密存储,从不返回,并在导入结束时抹除。请作为 multipart 中的 JSON 字符串发送。

options
object
status_mapping
object

对提供商默认状态映射的修改:将源状态映射到 Didit 状态。Not Finished 和 Abandoned 会被跳过并计数,绝不会被导入。

dry_run
boolean
默认值:false

统计迁移将导入的内容(按状态、已在 Didit 中、同一人、未完成划分)且不写入任何内容。任务结束状态为 READY;使用 POST /v3/session/imports/{importId}/start/ 启动它。

face_templates
boolean
默认值:false

根据导入的自拍照构建人脸模板,并对照应用的人脸库和黑名单进行搜索。匹配项仅会被标记以供审核。需要 lawful_basis_confirmed。

lawful_basis_confirmed
boolean
默认值:false

确认您拥有合法依据将这些自拍照共享给作为处理者的 Didit。

响应

导入任务已受理。轮询返回的 uuid,直至 status 变为 COMPLETED 或 FAILED。

uuid
string<uuid>
必填

导入任务 ID。使用此值轮询进度并获取行级错误。

status
enum<string>
必填
可用选项:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
必填
可用选项:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
必填
可用选项:
csv,
ndjson
source_filename
string
必填
total_rows
integer<int64>
必填
processed_rows
integer<int64>
必填
created_count
integer<int64>
必填
updated_count
integer<int64>
必填
skipped_count
integer<int64>
必填
failed_count
integer<int64>
必填
checkpoint_row
integer<int64>
total_media_bytes
integer<int64>
last_error
string | null
created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
state
enum<string>

控制台显示的任务状态;errors 表示任务已完成但存在被拒绝的行。

可用选项:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
可用选项:
file,
api,
provider
provider
string

迁移来源;对于文件或 API 导入则为空。

provider_options
object
credential_hint
string

迁移所保存密钥的前几个字符。密钥本身永远不会返回。

credentials_expires_at
string<date-time> | null
resumes_at
string<date-time> | null

因提供商速率限制而暂停的任务自行恢复的时间。

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

试运行发现的内容:total、by_status、already_in_didit、same_person、not_finished、failed、unmapped_statuses。

face_templates_enabled
boolean
lawful_basis_confirmed_at
string<date-time> | null
not_finished_count
integer<int64>
same_person_count
integer<int64>
face_templates_count
integer<int64>
face_duplicates_count
integer<int64>
face_blocklist_hits_count
integer<int64>
created_by_name
string | null
created_by_email
string | null
最后修改于 2026年11月7日