跳转到主要内容
PATCH
cURL
使用 PATCH 进行部分更新。要重命名工作流,只需发送 workflow_label。
要更改工作流中的检查项,请发送完整的目标 features 数组。这会替换之前的功能顺序和配置。
v3 API 让工作流保持简单:一条线性路径和一个最终状态步骤。此处不接受分支、操作节点和 Webhook 节点。

功能配置参考

在 PATCH 中发送 features 时,该数组会替换之前的功能顺序和配置。请重新包含所有必需的配置。 config 对象的具体内容取决于功能。请在 工作流功能配置 中查看完整的字段列表、默认值、必填设置、取值范围和示例。 对于 OCR,省略 config.documents_allowed、发送 null 或发送 {},即可允许所有受支持的证件类型。仅当您想将工作流限制为特定国家/地区或证件类型时,才需要包含该字段。对于 QUESTIONNAIRE,config.questionnaire_uuid 为必填项。

更新工作流设置

您可以在不修改功能列表的情况下更新会话级设置。只需发送您想更改的字段。
将列表、创建或获取 endpoint 返回的工作流 uuid 用作此 URL 中的 settings_uuid。

授权

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。

路径参数

settings_uuid
string<uuid>
必填

要更新的工作流版本 UUID。

请求体

application/json

更新工作流元数据或替换完整的线性功能列表。严格的字段白名单:此处未列出的任何键都将被拒绝并返回 400。

workflow_label
string

工作流的显示名称(最多 50 个字符)。

Maximum string length: 50
is_default
boolean

将此工作流设为新会话的默认工作流。

status
enum<string>

控制版本管理。省略此项将就地更新当前版本(草稿会自动发布)。对已发布的版本传入 published 将创建并返回新版本。draft 仅在当前版本仍为草稿时有效。

可用选项:
draft,
published
features
object[]

如果提供,将替换完整的功能顺序和配置。

Minimum array length: 1
is_white_label_enabled
boolean

为使用此工作流创建的会话启用白标定制。

is_desktop_allowed
boolean

允许验证流程在桌面端浏览器上运行。

max_retry_attempts
integer

验证被拒绝后允许的最大重试次数。0 表示在首次拒绝后即阻止用户。

必填范围: 0 <= x <= 10
retry_window_days
integer | null

用于计算重试次数的滑动时间窗口,以天为单位。null 执行历史累计限制。

必填范围: 1 <= x <= 365
face_liveness_max_attempts
integer

每次会话允许的最大活体检测提交次数。除非功能级配置覆盖,否则该值也会复制到生成的活体检测和年龄估算工作流节点中。

必填范围: 1 <= x <= 3
face_match_max_attempts
integer

每次会话允许的最大人脸比对提交次数。除非功能级配置覆盖,否则该值也会复制到生成的人脸比对工作流节点中。

必填范围: 1 <= x <= 3
session_expiration_time
integer

未完成会话过期前的秒数。最短 1 小时(3600),最长 4 周(2419200)。

必填范围: 3600 <= x <= 2419200

响应

工作流已更新。响应体为最终版本的完整配置(与 GET /v3/workflows/{settings_uuid}/ 相同的原始 VerificationSettings 结构)。当更新创建了新版本(在已发布的记录上发送了 status: "published")时,返回的 uuid 和 version 会与您执行 PATCH 操作时的不同,后续调用请使用返回的 uuid。

以下字段均为类型化字段;该对象还包含工作流配置的每个其他列(功能开关、阈值、警告操作、允许的证件、回调)作为附加属性。不适用于该 workflow_type 的字段为 null。

uuid
string<uuid>

每个版本对应的标识符(settings_uuid)。工作流的每个版本都有其独有的标识符。

workflow_id
string<uuid>

工作流所有版本共享的稳定标识符。使用它创建的会话将采用最新发布的版本。

workflow_label
string

工作流的显示名称。

workflow_type
enum<string> | null

工作流模板。对于未使用模板创建的图谱工作流为 null。

可用选项:
kyc,
kyb,
adaptive_age_verification,
biometric_authentication,
address_verification,
questionnaire_verification,
email_verification,
phone_verification,
null
is_default
boolean

这是否为该应用的默认工作流。

is_archived
boolean

已归档的工作流无法启动新会话。

version
integer

工作流内的版本号。

status
enum<string>

草稿版本可编辑;已发布版本不可更改,并用于新会话。

可用选项:
draft,
published
published_at
string<date-time> | null

此版本发布的时间。草稿为 null。

is_simple_workflow
boolean

当工作流没有自定义 workflow_graph 时为 true。

is_editable
boolean

仅对 draft 版本为 true。

workflow_url
string<uri>

启动此工作流会话的公开 URL。

workflow_graph
object | null

工作流的图谱结构(节点和边)。简单工作流为 null。

features
string

用 " + " 连接的已启用功能,例如 "OCR + LIVENESS"。

total_price
number | null

每次会话的价格;对于图谱工作流,为最昂贵路径的价格。

min_price
number | null

工作流中最便宜路径的价格。

max_price
number | null

工作流中最昂贵路径的价格。

special_add_on_prices
object | null

特定于组织的附加项价格,未设置时为 null。

max_retry_attempts
integer

验证被拒绝后允许的重试次数。

retry_window_days
integer | null

允许重试的天数。

session_expiration_time
integer

未完成会话过期前的秒数。

questionnaire
object | null

附加到工作流的问卷,或为 null。

kyb_role_settings
object[]

针对 KYB 关键人员的按角色验证设置。

created_at
string<date-time>
updated_at
string<date-time>
signature_availability
object

当前哪些电子签名等级可以签署。在设置 signature_level 之前请检查此项。在 kyc、kyb 和图谱工作流中返回。

is_bank_verification_enabled
boolean

简易 KYC 或 KYB 工作流是否运行银行验证。它在联系方式步骤(以及位置验证)之后、数据库核验、AML 及 IP 分析之前运行。银行验证目前尚未正式公开发布:在未启用的情况下开启将被拒绝。

bank_verification_config
object

简单工作流的银行验证设置,包含与 BANK_VERIFICATION 节点相同的键(例如 bank_countries 和 bank_method_order)。未知键将被丢弃。每个键均为可选,缺少的键保持其默认值,因此 {} 表示全部使用默认值。参见银行验证设置。

示例:
is_geolocation_enabled
boolean

简易 KYC 工作流是否运行位置验证。它在联系方式步骤之后、银行验证和数据库核验之前运行。企业(KYB)工作流无法运行该验证。

geolocation_config
object

简易工作流的位置验证设置,具有与 GEOLOCATION 节点相同的键(例如 is_geolocation_geofencing_enabled 和 geolocation_max_attempts)。未知的键将被丢弃。每个键都是可选的,缺少的键保持其默认值,因此 {} 表示全部使用默认值。

示例:
最后修改于 2026年11月7日